NAME¶
pvm_mkbuf - Creates a new message buffer.
SYNOPSIS¶
C int bufid = pvm_mkbuf( int encoding )
Fortran call pvmfmkbuf( encoding, bufid )
PARAMETERS¶
- encoding
- Integer specifying the buffer's encoding scheme.
Options in C are:
Encoding value MEANING
PvmDataDefault 0 XDR
PvmDataRaw 1 no encoding
PvmDataInPlace 2 data left in place
Option names in Fortran are:
Encoding value MEANING
PVMDEFAULT 0 XDR
PVMRAW 1 no encoding
PVMINPLACE 2 data left in place
- bufid
- Integer message buffer identifier returned. Values less than zero indicate
an error.
DESCRIPTION¶
The routine
pvm_mkbuf creates a new message buffer and sets its encoding
status to
encoding. If pvm_mkbuf is successful,
bufid will be
the identifier for the new buffer, which can be used as a send buffer. If some
error occurs then
bufid will be < 0.
With the default setting XDR encoding is used when packing the message because
PVM can not know if the user is going to add a heterogeneous machine before
this message is sent. The other options to encoding allow the user to take
advantage of knowledge about his virtual machine even when it is
heterogeneous. For example, if the user knows that the next message will only
be sent to a machine that understands the native format, then he can use
PvmDataRaw encoding and save on encoding costs.
PvmDataInPlace encoding specifies that data be left in place during packing. The
message buffer only contains the sizes and pointers to the items to be sent.
When pvm_send is called the items are copied directly out of the user's
memory. This option decreases the number of times a message is copied at the
expense of requiring the user to not modify the items between the time they
are packed and the time they are sent.
pvm_mkbuf is required if the user wishes to manage multiple message buffers and
should be used in conjunction with pvm_freebuf. pvm_freebuf should be called
for a send buffer after a message has been sent and is no longer needed.
Receive buffers are created automatically by the pvm_recv and pvm_nrecv routines
and do not have to be freed unless they have been explicitly saved with
pvm_setrbuf.
Typically multiple send and receive buffers are not needed and the user can
simply use the pvm_initsend routine to reset the default send buffer.
There are several cases where multiple buffers are useful. One example where
multiple message buffers are needed involves libraries or graphical interfaces
that use PVM and interact with a running PVM application but do not want to
interfere with the application's own communication.
When multiple buffers are used they generally are made and freed for each
message that is packed.
RESTRICTIONS¶
PvmDataInPlace allows only dense (stride = 1) data in version 3.3. It cannot be
used on shared memory (*MP) architectures; a PvmNotImpl error will occur at
send time.
EXAMPLES¶
C:
bufid = pvm_mkbuf( PvmDataRaw );
/* send message */
info = pvm_freebuf( bufid );
Fortran:
CALL PVMFMKBUF(PVMDEFAULT, MBUF)
* SEND MESSAGE HERE
CALL PVMFFREEBUF( MBUF, INFO )
ERRORS¶
These error conditions can be returned by
pvm_mkbuf
PvmBadParam giving an invalid encoding value.
PvmNoMem Malloc has failed. There is not enough memory
to create the buffer
SEE ALSO¶
pvm_initsend(3PVM), pvm_freebuf(3PVM)