MKBUF(3PVM) PVM Version 3.4 MKBUF(3PVM)NAMEpvm_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 encod‐
ing 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_free‐
buf 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 buf‐
fer.
There are several cases where multiple buffers are useful. One example
where multiple message buffers are needed involves libraries or graphi‐
cal 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 ALSOpvm_initsend(3PVM), pvm_freebuf(3PVM)
30 August, 1993 MKBUF(3PVM)
