MKBUF(3PVM)

💖 MKBUF(3PVM) — aka pvm_mkbuf 💖

okay bestie, welcome to the PVM Version 3.4 manual, page MKBUF(3PVM). this is the one where we make a brand new message buffer from scratch. it's giving arts and crafts but for parallel computing. let's go 🎀

---

✨ NAME ✨

pvm_mkbuf — Creates a new message buffer.

like, it literally builds you a fresh buffer. no cap.

---

✨ SYNOPSIS ✨

C:

int bufid = pvm_mkbuf( int encoding )

Fortran:

call pvmfmkbuf( encoding, bufid )

---

✨ PARAMETERS ✨

• encoding — an Integer that says which encoding scheme your buffer is gonna use. here are your options, and bestie, the numbers MATTER:

in C:

• PvmDataDefault = 0 — XDR
• PvmDataRaw = 1 — no encoding
• PvmDataInPlace = 2 — data left in place

and the Fortran option names are:

• PVMDEFAULT = 0 — XDR
• PVMRAW = 1 — no encoding
• PVMINPLACE = 2 — data left in place

• bufid — the Integer message buffer identifier that gets returned to you. if the value is less than zero, that's an error, no it's not a vibe, it's a problem 🫠

---

✨ DESCRIPTION ✨

so 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, and you can use that as a send buffer. if some error occurs then bufid will be < 0. rude, but okay.

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. PVM is not a mind reader bestie, it's just doing its best 💅

the other options to encoding let the user 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. savings!! we love a budget-friendly era ✨

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. so like... do not touch. hands off. periodt 🙈

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. clean up after yourself, queen 👑

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. so those ones are self-sufficient, main character energy fr fr.

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. lowkey the easy path, and honestly? valid.

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. they're just trying to coexist, bestie 🤝

when multiple buffers are used they generally are made and freed for each message that is packed. one message, one buffer, one little lifecycle. iconic.

---

🚨 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. so like, do NOT try it, the error will find you 😭

---

✨ 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. bestie. you gave it a bad number. it's judging you gently.
• PvmNoMem — Malloc has failed. There is not enough memory to create the buffer. out of memory, out of luck 🫶

---

🌈 SEE ALSO 🌈

• pvm_initsend(3PVM)
• pvm_freebuf(3PVM)

---

and that's the whole page, bestie!! go forth and buffer responsibly 💖✨🎀

mwah 💋 — this has been PVM Version 3.4, page MKBUF(3PVM), dated 30 August, 1993. yeah, 1993. vintage. archival. still slaying.