MKBUF(3PVM)

💖 MKBUF(3PVM) 💖

okay bestie, welcome to MKBUF from PVM Version 3.4 — she's the one who hands you a shiny new message buffer, and honestly? iconic behavior.

---

✨ NAME ✨

pvm_mkbuf — creates a new message buffer. that's it, that's the whole job, and she does it flawlessly 💅

---

🦋 SYNOPSIS 🦋

C:

int bufid = pvm_mkbuf( int encoding )

Fortran:

call pvmfmkbuf( encoding, bufid )

---

🎀 PARAMETERS 🎀

• encoding — an integer that says what the buffer's encoding scheme is gonna be. here's the menu, C edition:
  • PvmDataDefault — 0 — XDR
  • PvmDataRaw — 1 — no encoding
  • PvmDataInPlace — 2 — data left in place

and for the Fortran girlies, the option names go like this:

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

• bufid — the integer message buffer identifier that gets returned. any value less than zero? that's an error, no cap. 😭

---

🌸 DESCRIPTION 🌸

so pvm_mkbuf creates a brand new message buffer and sets its encoding status to encoding. if it goes well, bufid is the identifier for your new buffer, and you can totally use it as a send buffer. if something goes wrong, bufid will be < 0. rude, but fair.

with the default setting, XDR encoding gets used when packing the message, because PVM literally cannot know if you're about to add a heterogeneous machine before this message is sent. the other encoding options let you flex what you know about your own virtual machine, even when it is heterogeneous. like, say you know the next message is only ever going to a machine that understands the native format — then you can use PvmDataRaw encoding and save on encoding costs. ate. 🔥

PvmDataInPlace encoding says data gets left in place during packing. the message buffer then only holds the sizes and pointers to the items to be sent. when pvm_send is called, those items are copied directly out of the user's memory. this option cuts down the number of times a message gets copied — the trade-off being that you, the user, must not modify the items between the time they're packed and the time they're sent. so don't touch them. periodt.

pvm_mkbuf is required if you wanna manage multiple message buffers, and it should be used together 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, bestie.

receive buffers are created automatically by the pvm_recv and pvm_nrecv routines, and they don't have to be freed unless they've been explicitly saved with pvm_setrbuf.

typically you don't even need multiple send and receive buffers — most people can just use the pvm_initsend routine to reset the default send buffer. simple life, honestly.

but 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 don't want to interfere with the application's own communication. respectful queen behavior 🫶

when multiple buffers are used, they generally get made and freed for each message that's 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. so like… heads up 💀

---

⭐ 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)

---

and that's the whole page, bestie 💖 this was MKBUF(3PVM), dated 30 August, 1993, from PVM Version 3.4 — go forth and buffer responsibly, ily, mwah 🎀✨