Pack and Unpack

Up: Noncontiguous Operations Next: Implementation of Noncontiguous Operations Previous: Noncontiguous Operations

MPI contains routines to pack and unpack data. These routines are MPI_Pack, MPI_Unpack, and MPI_Pack_size. An MPI implementation must provide these; further, a user may send data that has be constructed with MPI_Pack with datatype MPI_PACKED and receive it either with datatype MPI_PACKED or with any MPI datatype with the same type signature that went into the packed data. Because of this, the device must provide the routines to pack and unpack data. Of course, many implementations of the device may use the model implementation's version of these routines.

The MPI pack and unpack routines are designed to handle data on a communicator-wide basis. That is, data is packed relative to a communicator; a natural implementation is to pick a data representation that is a good choice for all members of the communicator (including the sender!). However, a common use of these routines in an implementation is to pack and unpack data sent with the point-to-point operations. In order to provide for this use, the ADI's version of the pack and unpack routines include a partner field, which is either a rank in the communicator of the partner (sender or receiver) or MPI_ANY_SOURCE, which indicates ``any member of the communicator'' and most closely matches the MPI MPI_Pack and MPI_Unpack routines.

Note that just as send and receive seem very symmetric but are not, so are pack and unpack in fact unsymmetric. On the pack (sender) side, the sender has some freedom in choosing just how to represent the data. On the receiver's side, the data must be dealt with as it arrives. Thus, on the sending side, the sender picks the message representation (msgrep, a value passed to the receiver) and the routine to set the data up in this way (the message action msgact in the routines below). On the receiving side, only the msgrep is available to the receiver; from this it must determine how to unpack the data.

On the senders side, the routine MPID_Msg_rep determines the message representation and action from the communicator, destination, and datatype. Note for example that if the datatype is MPI_PACKED, the msgact will be MPID_MSG_OK (just copy) while the msgrep will be whatever is used for packed data (e.g., MPID_MSGFORM_XDR).

MPID_Msg_rep( comm, partner, datatype, &msgrep, &msgact )

comm: Communicator for the operation.
partner: Rank of ``partner'' process or MPI_ANY_SOURCE.
datatype: struct MPIR_DATATYPE * of input buffer. Allows the detection of the special case of MPI_PACKED.
msgrep: Message representation; this is an output value.
msgact: Action for message representation; this output value may be used as input to the pack/unpack routines to indicate how to process the message. This is a MPID_Msg_pack_t type (enum int).

On the receiver's side, the message action can be determined from the msgrep and the datatype. Just as for sending, if the datatype is MPI_PACKED, then the msgact may be just copy.

MPID_Msg_act( comm, partner, datatype, msgrep, &msgact )

comm: Communicator for the operation.
partner: Rank of ``partner'' process or MPI_ANY_SOURCE.
datatype: MPI datatype of input buffer. Allows the detection of the special case of MPI_PACKED.
msgrep: Message representation; this is an input value (from the message envelope).
msgact: Action for message representation; this output value may be used as input to the unpack routines to indicate how to process the message.

MPID_Pack( src, count, datatype, dest, maxcount, &position,  
           comm, partner, msgrep, msgact, &error_code )

src: Address of the input buffer.
count: Number of item in input buffer.
datatype: MPI datatype of input buffer.
dest: Address of the output buffer.
maxcount: Size of dest in bytes.
position: Current location in dest. Set to 0 on first call; updated by routine (allows multiple calls to MPID_Pack).
comm: Communicator for the operation.
partner: Rank of ``partner'' process or MPI_ANY_SOURCE.
msgrep: Message representation type.
msgact: Action for message representation.
error_code: The result of the action (an MPI error code). This may be set only if the value would not be MPI_SUCCESS. In other words, an implementation is free to not set this unless there is an error. The error code was made an argument so that an implementation as a macro would be easier.

MPID_Unpack( src, maxcount, msgrep, &in_position,  
             dest, count, datatype, &out_position, 
             comm, partner, &error_code )

src: Address of the input buffer.
maxcount: Size of src in bytes.
msgrep: Message representation.
in_position: Current Location in src. Set to 0 on first call; updated by routine.
dest: Address of the output buffer.
count: Maximum number of datatype items to unpack.
datatype: MPI datatype of input buffer.
out_position: Current location in dest. Set to 0 on first call.
comm: Communicator for the operation.
partner: Rank of ``partner'' process or MPI_ANY_SOURCE. routine for subsequent calls
error_code: The result of the action (an MPI error code). This may be set only if the value would not be MPI_SUCCESS. In other words, an implementation is free to not set this unless there is an error. The error code was made an argument so that an implementation as a macro would be easier.

MPID_Pack_size( count, datatype, msgact, &size )

count: Number of datatype items to pack.
datatype: MPI datatype to pack.
msgact: Message action
size: Number of bytes needed to pack data (this may be larger than actually needed, though it should be ``close'').

If the destination buffer is too small to contain the packed/unpacked data, the error code MPI_ERR_TRUNCATE is returned. All position arguments are in bytes. The msgrep value is an integer that is accompanies the message (in the envelope) from the sender to the receiver and allows the implementation to pick the message representation dynamically (rather than fixing on XDR or network-byte-order for all messages).

Up: Noncontiguous Operations Next: Implementation of Noncontiguous Operations Previous: Noncontiguous Operations