Open MPI logo

MPI_Unpack(3) man page (version 1.2.9)

  |   Home   |   Support   |   FAQ   |  

« Return to documentation listing



NAME

       MPI_Unpack - Unpacks a datatype into contiguous memory.

SYNTAX


C Syntax

       #include <mpi.h>
       int MPI_Unpack(void *inbuf, int insize, int *position,
            void *outbuf, int outcount, MPI_Datatype datatype,
            MPI_Comm comm)

Fortran Syntax

       INCLUDE 'mpif.h'
       MPI_UNPACK(INBUF, INSIZE, POSITION, OUTBUF, OUTCOUNT,
            DATATYPE, COMM, IERROR)
            <type>    INBUF(*), OUTBUF(*)
            INTEGER   INSIZE, POSITION, OUTCOUNT, DATATYPE,
                 COMM, IERROR

C++ Syntax

       #include <mpi.h>
       void Datatype::Unpack(const void* inbuf, int insize,
            void *outbuf, int outcount, int& position,
            const Comm& comm) const

INPUT PARAMETERS

       inbuf     Input buffer start (choice).

       insize    Size of input buffer, in bytes (integer).

       outcount  Number of items to be unpacked (integer).

       datatype  Datatype of each output data item (handle).

       comm      Communicator for packed message (handle).

INPUT/OUTPUT PARAMETER

       position  Current position in bytes (integer).

OUTPUT PARAMETERS

       outbuf    Output buffer start (choice).

       IERROR    Fortran only: Error status (integer).

DESCRIPTION

       Unpacks  a  message  into  the receive buffer specified by outbuf, out-
       count, datatype from the buffer space specified by  inbuf  and  insize.
       The  output buffer can be any communication buffer allowed in MPI_Recv.
       The input buffer is a contiguous storage area containing insize  bytes,
       starting  at  address  inbuf.  The input value of position is the first
       location in the input buffer occupied by the packed  message.  position
       is  incremented  by  the size of the packed message, so that the output
       received. The actual number of items  received  is  determined  by  the
       length of the incoming message. In MPI_Unpack, the count argument spec-
       ifies the actual number of items that are to be unpacked; the "size" of
       the  corresponding message is the increment in position. The reason for
       this change is that the "incoming message size"  is  not  predetermined
       since  the user decides how much to unpack; nor is it easy to determine
       the "message size" from the number of items to be unpacked.

       To understand the behavior of pack and  unpack,  it  is  convenient  to
       think  of  the data part of a message as being the sequence obtained by
       concatenating the successive values sent  in  that  message.  The  pack
       operation  stores  this sequence in the buffer space, as if sending the
       message to that buffer. The unpack operation  retrieves  this  sequence
       from  buffer  space, as if receiving a message from that buffer. (It is
       helpful to think of internal Fortran files or sscanf in C for a similar
       function.)

       Several messages can be successively packed into one packing unit. This
       is effected by several successive related calls to MPI_Pack, where  the
       first  call  provides position = 0, and each successive call inputs the
       value of position that was output by the previous call,  and  the  same
       values  for  outbuf, outcount, and comm. This packing unit now contains
       the equivalent information that would have been stored in a message  by
       one  send  call  with  a send buffer that is the "concatenation" of the
       individual send buffers.

       A packing unit can be sent using type MPI_Packed. Any point-to-point or
       collective  communication  function can be used to move the sequence of
       bytes that forms the packing unit from one  process  to  another.  This
       packing  unit can now be received using any receive operation, with any
       datatype: The type-matching rules are relaxed for  messages  sent  with
       type MPI_Packed.

       A  message  sent  with  any type (including MPI_Packed) can be received
       using the type MPI_Packed. 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. This is effected by  several
       successive  related  calls to MPI_Unpack, where the first call provides
       position = 0, and each successive call inputs  the  value  of  position
       that  was  output  by the previous call, and the same values for inbuf,
       insize, and comm.

       The concatenation of two packing units is  not  necessarily  a  packing
       unit;  nor is a substring of a packing unit necessarily a packing unit.
       Thus, one cannot concatenate two packing  units  and  then  unpack  the
       result as one packing unit; nor can one unpack a substring of a packing
       unit as a separate packing unit. Each packing unit that was 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.

ERRORS

       Almost all MPI routines return an error value; C routines as the  value
       of  the  function  and Fortran routines in the last argument. C++ func-
       tions do not return errors. If the default  error  handler  is  set  to
       MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism

SEE ALSO

       MPI_Pack
       MPI_Pack_size

Open MPI 1.2                    September 2006            MPI_Unpack(3OpenMPI)

« Return to documentation listing