MPI_UNPACK(3)

📦
version 5.0.10 · 7 versions
, in ubuntu stonking

💖 MPI_UNPACK(3) 💖

okay bestie, welcome to the Open MPI manual page for MPI_Unpack — she unpacks a datatype into contiguous memory 💅 and honestly? she's kind of the moment. no cap.

✨ SYNTAX ✨

🎀 C Syntax

#include <mpi.h>

int MPI_Unpack(const void *inbuf, int insize, int *position,
     void *outbuf, int outcount, MPI_Datatype datatype,
     MPI_Comm comm)

🎀 Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_UNPACK(INBUF, INSIZE, POSITION, OUTBUF, OUTCOUNT,
     DATATYPE, COMM, IERROR)
     <type>  INBUF(*), OUTBUF(*)
     INTEGER INSIZE, POSITION, OUTCOUNT, DATATYPE,
             COMM, IERROR

🎀 Fortran 2008 Syntax

USE mpi_f08
MPI_Unpack(inbuf, insize, position, outbuf, outcount, datatype, comm,
             ierror)
     TYPE(*), DIMENSION(..), INTENT(IN) :: inbuf
     TYPE(*), DIMENSION(..) :: outbuf
     INTEGER, INTENT(IN) :: insize, outcount
     INTEGER, INTENT(INOUT) :: position
     TYPE(MPI_Datatype), INTENT(IN) :: datatype
     TYPE(MPI_Comm), INTENT(IN) :: comm
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

🌸 INPUT PARAMETERS 🌸

  • inbuf — where the input buffer starts (choice). the little storage unit bestie, the vibe of it all 💖
  • insize — how big that input buffer is, in bytes (integer).
  • outcount — how many items we're unpacking (integer).
  • datatype — the datatype of each output data item (handle).
  • comm — the communicator for the packed message (handle).

🦋 INPUT/OUTPUT PARAMETER 🦋

  • position — current position, in bytes (integer). she comes in with a value and she leaves with a value, main character energy fr.

🍓 OUTPUT PARAMETERS 🍓

  • outbuf — where the output buffer starts (choice).
  • ierror — Fortran only: error status (integer).

✨ DESCRIPTION ✨

so basically 💜 MPI_Unpack unpacks a message into the receive buffer you specified with outbuf, outcount, and datatype, pulling it out of the buffer space you gave as inbuf and insize. the output buffer can be literally any communication buffer that's allowed in MPI_Recv. the input buffer is one contiguous storage area holding insize bytes, starting at address inbuf. the input value of position is the first location in the input buffer that the packed message occupies. then position gets incremented by the size of the packed message, so the output value of position is the first location in the input buffer right after everything the unpacked message was sitting on. and comm? that's the communicator used to receive the packed message. periodt. 👑

🌈 NOTES 🌈

ok first things first, clock the difference between MPI_Recv and MPI_Unpack: in MPI_Recv, the count argument is the maximum number of items that can be received, and the actual number received is decided by the length of the incoming message. but in MPI_Unpack, the count argument is the actual number of items to be unpacked, and the "size" of the corresponding message is the increment in position. why the switcheroo? because the "incoming message size" isn't predetermined — the user decides how much to unpack — and it's not easy to figure out the "message size" from the number of items to be unpacked either. it's giving user's choice 🫶

to understand pack and unpack behaviour, the cutest mental model is this: think of the data part of a message as the sequence you get by concatenating the successive values sent in that message. the pack operation stores this sequence in the buffer space, as if it were sending the message to that buffer. the unpack operation retrieves this sequence from buffer space, as if it were receiving a message from that buffer. (ngl, it helps to think of internal Fortran files or sscanf in C for a similar function. iykyk 💅)

several messages can be packed one after another into a single packing unit. how? with several successive related calls to MPI_Pack, where the first call provides position = 0, and every successive call takes as input the value of position that the previous call output, plus the same values for outbuf, outcount, and comm. that packing unit now holds the equivalent information that a single send call would've stored in a message, with a send buffer that is the "concatenation" of the individual send buffers. slay. ✨

a packing unit can be sent using type MPI_Packed. any point-to-point or collective communication function can move that sequence of bytes forming the packing unit from one process to another. and then this packing unit can be received with any receive operation, using any datatype — because the type-matching rules are relaxed for messages sent with type MPI_Packed. iconic.

also: a message sent with any type (including MPI_Packed) can be received using the type MPI_Packed. and such a message can then be unpacked by calls to MPI_Unpack. 🎀

a packing unit (or a message created by a regular, "typed" send) can be unpacked into several successive messages too. that's done with several successive related calls to MPI_Unpack, where the first call provides position = 0, and each successive call takes as input the value of position output by the previous call, plus the same values for inbuf, insize, and comm.

⚠️ okay listen, big one: the concatenation of two packing units is not necessarily a packing unit, and a substring of a packing unit is not necessarily a packing unit either. so you cannot concatenate two packing units and then unpack the result as one packing unit — and you cannot unpack a substring of a packing unit as a separate packing unit. every packing unit created by a related sequence of pack calls, or by a regular send, must be unpacked as a unit, by a sequence of related unpack calls. no shortcuts bestie, that's just the rules 😭

💀 ERRORS 💀

almost all MPI routines return an error value: C routines as the return result of the function, and Fortran routines in the last argument.

before that error value comes back, the current MPI error handler associated with the communication object (e.g., communicator, window, file) gets called. if no communication object is associated with the MPI call, then the call counts as attached to MPI_COMM_SELF and will call the associated MPI error handler. when MPI_COMM_SELF isn't initialized (i.e., before MPI_Init/MPI_Init_thread, after MPI_Finalize, or when using the Sessions Model exclusively), the error raises the initial error handler. that initial error handler can be changed by calling MPI_Comm_set_errhandler on MPI_COMM_SELF when using the World model, or by the mpi_initial_errhandler CLI argument to mpiexec, or by an info key to MPI_Comm_spawn/MPI_Comm_spawn_multiple. and if no other appropriate error handler has been set, then the MPI_ERRORS_RETURN error handler is called for MPI I/O functions, and the MPI_ERRORS_ABORT error handler is called for all other MPI functions.

Open MPI ships three predefined error handlers you can use, and here they are, no gatekeeping:

  • MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. 💀
  • MPI_ERRORS_ABORT — an error handler that can be invoked on a communicator, window, file, or session. when called on a communicator, it acts as if MPI_Abort was called on that communicator. if called on a window or file, it acts as if MPI_Abort was called on a communicator containing the group of processes in the corresponding window or file. if called on a session, it aborts only the local process.
  • MPI_ERRORS_RETURN — returns an error code to the application.

MPI applications can also implement their own error handlers by calling:

  • MPI_Comm_create_errhandler then MPI_Comm_set_errhandler
  • MPI_File_create_errhandler then MPI_File_set_errhandler
  • MPI_Session_create_errhandler then MPI_Session_set_errhandler or at MPI_Session_init
  • MPI_Win_create_errhandler then MPI_Win_set_errhandler

and ngl: MPI does not guarantee that an MPI program can continue past an error. that's a hard fact, not a vibe.

check the MPI man page for a full list of MPI error codes, and see the Error Handling section of the MPI-3.1 standard for more info. 🧚

👑 See also: 👑

  • MPI_Pack
  • MPI_Pack_size

2003-2026, The Open MPI Community

and that's the whole page babes 💖 this was MPI_UNPACK(3) from Open MPI, dated Sep 10, 2026 — go unpack something iconic, you've got this ✨🌸💅

📦 where this page comes from