PRECV(3PVM)

📦 version 3.4.6, in debian bookworm, ubuntu jammy

💌 PRECV — the pvm_precv page, but make it make sense

okay bestie, sit down, hydrate, because we're learning pvm_precv from the PVM Version 3.4 manual and honestly? it's giving "receive a message directly into a buffer." no cap. that's the whole NAME. 🫶

✨ NAME ✨

pvm_precv — receive a message directly into a buffer. that's it, that's the girl. 💅

🌸 SYNOPSIS 🌸

C bestie:

int info = pvm_precv( int tid, int msgtag, char *buf,
                      int len, int datatype, int *atid,
                      int *atag, int *alen )

Fortran bestie:

call pvmfprecv( tid, msgtag, buf, len, datatype,
                atid, atag, alen, info )

🎀 PARAMETERS 🎀

the whole cast, no skips:

  • tid — Integer task identifier of the sending process (the one you're matching against, iykyk).
  • msgtag — Integer message tag to match. and listen, msgtag should be >= 0. respect the bit. 😤
  • buf — Pointer to a buffer to receive into. the landing zone.
  • len — Length of buffer (in multiple of data type size). math girlies rise.
  • datatype — Type of data that buf points to (full list further down, don't scroll past it 🫣).
  • atid — Returns actual TID of sender. the receipts. 🧾
  • atag — Returns actual message tag.
  • alen — Returns actual message length.
  • info — Returns PvmOk on success. Values less than zero indicate an error. 💀

💖 DESCRIPTION 💖

so pvm_precv blocks the process until a message with label msgtag has arrived from tid. like, it will simply wait. main character patience. then it places the contents of the message in the supplied buffer, buf, up to a maximum length of len * (size of data type).

and it's flexible, okay? pvm_precv can receive messages sent by pvm_psend, pvm_send, pvm_mcast, or pvm_bcast. four whole senders. she's not picky. 💅

🦋 the wildcard lore (this part matters)

a -1 in msgtag or tid matches anything. this gives you the following options, and yes we're listing all of them:

  1. if tid = -1 and msgtag is defined by the user, then pvm_precv will accept a message from any process which has a matching msgtag.
  2. if msgtag = -1 and tid is defined by the user, then pvm_precv will accept any message that is sent from process tid.
  3. if tid = -1 and msgtag = -1, then pvm_precv will accept any message from any process. absolute chaos mode, we love her. 😌

🍓 the datatype menu (C edition)

in C the datatype parameter must be one of the following, depending on the type of data to be unpacked:

[Version 3.3.0 — This parameter only determines message length, not data conversion. It only unpacks raw bytes]
  • PVM_STR — string
  • PVM_BYTE — byte
  • PVM_SHORT — short
  • PVM_INT — int
  • PVM_FLOAT — real
  • PVM_CPLX — complex
  • PVM_DOUBLE — double
  • PVM_DCPLX — double complex
  • PVM_LONG — long integer
  • PVM_USHORT — unsigned short int
  • PVM_UINT — unsigned int
  • PVM_ULONG — unsigned long int

in Fortran, use the same data types specified for unpack. matching set, bestie. ✨

🌈 message order tea (PVM guarantees this, fr fr)

the PVM model guarantees the following about message order. if task 1 sends message A to task 2, then task 1 sends message B to task 2, message A will arrive at task 2 before message B. and moreover, if both messages arrive before task 2 does a receive, then a wildcard receive will always return message A. queue behavior? iconic. 👑

💜 success + blocking behavior

if pvm_precv is successful, info will be = 0. if some error occurs then info will be < 0.

pvm_precv is blocking, which means the routine waits until a message matching the user specified tid and msgtag arrives at the local pvmd. but if the message has already arrived then pvm_precv returns immediately with the message. no waiting around for no reason, she's efficient. ⭐

also, pvm_precv does not affect the state of the current receive message buffer (the one created by the other receive functions). hands off, respectfully. 🙈

⚠️ WARNINGS ⚠️

ok this is the scary part, read it, i'm serious, this is not a vibe, this is a whole hazard. 🚨

in some versions of PVM (CM5, I860 and PGON), messages sent using pvm_psend must be received only by pvm_precv, likewise those sent with pvm_send must be received by pvm_recv, pvm_nrecv or pvm_trecv. pvm_psend is not compatible with pvm_recv (nor pvm_send with pvm_precv). in addition, pvm_probe is not interoperable with pvm_psend.

this problem occurs because nonstandard message headers are used for efficiency in the pvm_psend function. in the generic Unix version of PVM, the calls are fully interoperable. so it depends on the platform, bestie. check before you commit. 😭

and one more: the message tag space is shared between pvm_send and pvm_psend, so you must be careful to avoid selecting the wrong message (for example by using a wildcard to match the message). wildcard = risky behavior. lowkey thrilling, highkey dangerous. 💀

🧚 EXAMPLES 🧚

C:

info = pvm_precv( tid, msgtag, array, cnt, PVM_FLOAT,
                  &src, &rtag, &rlen );

Fortran:

CALL PVMFPRECV( -1, 4, BUF, CNT, REAL4,
>                SRC, RTAG, RCNT, INFO )

look at her go. ate. 🔥

😭 ERRORS 😭

these error conditions can be returned by pvm_precv:

  • PvmBadParam — giving an invalid tid, msgtag, or datatype. (basically: you handed her something wrong.)
  • PvmSysErr — pvmd not responding. (the daemon ghosted you, rip. 👻)

👑 SEE ALSO 👑

go read these next, bestie, they're in the group chat too:

  • pvm_psend(3PVM)
  • pvm_recv(3PVM)

and that's the page!! 15 March, 1994 is the date on this one and it's from the PVM Version 3.4 manual, which, yes, is older than all of us, but she still slays. mwah. 💖🎀🦋✨

PRECV(3PVM) — periodt. 🌸

📦 where this page comes from