pvm_mkbuf(3)

1MKBUF(3PVM)                     PVM Version 3.4                    MKBUF(3PVM)
2
3
4

NAME

6       pvm_mkbuf - Creates a new message buffer.
7
8

SYNOPSIS

10       C    int bufid = pvm_mkbuf( int encoding )
11
12       Fortran   call pvmfmkbuf( encoding, bufid )
13
14

PARAMETERS

16       encoding
17               Integer specifying the buffer's encoding scheme.
18               Options in C are:
19                    Encoding value           MEANING
20                    PvmDataDefault      0    XDR
21                    PvmDataRaw          1    no encoding
22                    PvmDataInPlace      2    data left in place
23
24               Option names in Fortran are:
25                    Encoding value           MEANING
26                    PVMDEFAULT          0    XDR
27                    PVMRAW              1    no encoding
28                    PVMINPLACE          2    data left in place
29
30       bufid   Integer  message  buffer identifier returned.  Values less than
31               zero indicate an error.
32
33

DESCRIPTION

35       The routine pvm_mkbuf creates a new message buffer and sets its  encod‐
36       ing  status to encoding.  If pvm_mkbuf is successful, bufid will be the
37       identifier for the new buffer, which can be used as a send buffer.   If
38       some error occurs then bufid will be < 0.
39
40       With  the default setting XDR encoding is used when packing the message
41       because PVM can not know if the user is going to  add  a  heterogeneous
42       machine  before  this  message  is sent.  The other options to encoding
43       allow the user to take advantage of knowledge about his virtual machine
44       even  when it is heterogeneous. For example, if the user knows that the
45       next message will only be sent to a machine that understands the native
46       format, then he can use PvmDataRaw encoding and save on encoding costs.
47
48       PvmDataInPlace  encoding  specifies  that  data be left in place during
49       packing.  The message buffer only contains the sizes  and  pointers  to
50       the  items  to  be  sent.  When pvm_send is called the items are copied
51       directly out of the user's memory. This option decreases the number  of
52       times  a  message is copied at the expense of requiring the user to not
53       modify the items between the time they are packed and the time they are
54       sent.
55
56       pvm_mkbuf  is  required  if  the user wishes to manage multiple message
57       buffers and should be used in conjunction with pvm_freebuf.   pvm_free‐
58       buf  should  be  called for a send buffer after a message has been sent
59       and is no longer needed.
60
61       Receive buffers are created automatically by the pvm_recv and pvm_nrecv
62       routines  and  do not have to be freed unless they have been explicitly
63       saved with pvm_setrbuf.
64
65       Typically multiple send and receive buffers are not needed and the user
66       can  simply use the pvm_initsend routine to reset the default send buf‐
67       fer.
68
69       There are several cases where multiple buffers are useful.  One example
70       where multiple message buffers are needed involves libraries or graphi‐
71       cal interfaces that use PVM and interact with a running PVM application
72       but do not want to interfere with the application's own communication.
73
74       When  multiple  buffers  are used they generally are made and freed for
75       each message that is packed.
76
77

RESTRICTIONS

79       PvmDataInPlace allows only dense (stride = 1) data in version 3.3.   It
80       cannot be used on shared memory (*MP) architectures; a PvmNotImpl error
81       will occur at send time.
82
83

EXAMPLES

85       C:
86            bufid = pvm_mkbuf( PvmDataRaw );
87            /* send message */
88            info = pvm_freebuf( bufid );
89
90       Fortran:
91            CALL PVMFMKBUF(PVMDEFAULT, MBUF)
92       *    SEND MESSAGE HERE
93            CALL PVMFFREEBUF( MBUF, INFO )
94
95

ERRORS

97       These error conditions can be returned by pvm_mkbuf
98            PvmBadParam    giving an invalid encoding value.
99            PvmNoMem       Malloc has failed. There is not enough memory
100                           to create the buffer
101