PRECV(3PVM)

👑 PRECV — pvm_precv, from the PVM Version 3.4 manual, section 3PVM 💖

okay bestie, sit down, hydrate, because today we're talking about pvm_precv — the girl who receives a message directly into a buffer. no middleman. no extra steps. she's efficient, she's iconic, and she's gonna block until your message shows up. periodt. ✨

---

🌸 NAME 🌸

pvm_precv — Receive a message directly into a buffer.

like literally straight into buf. she does not do detours. 💅

---

🎀 SYNOPSIS 🎀

C:

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

Fortran:

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

two languages, one queen. 🌈

---

💜 PARAMETERS 💜

• tid — Integer task identifier of the sending process (to match). the sender's ID, so you can be like "yeah I'm only taking messages from that one."
• msgtag — Integer message tag (to match). msgtag should be >= 0. heads up, bestie, negative tags are for the wildcard stuff below, not for matching.
• buf — Pointer to a buffer to receive into. this is where the message content lands. make room. 🛏️
• len — Length of buffer (in multiple of data type size). so it's counts, not bytes. do the math or suffer.
• datatype — Type of data to which buf points (see below). scroll down, it's all listed, no gatekeeping here. 🦋
• atid — Returns actual TID of sender. so you know who actually showed up to the party.
• atag — Returns actual message tag. the real tag, not the wildcard you asked for.
• alen — Returns actual message length. how much actually arrived.
• info — Returns PvmOk on success. Values less than zero indicate an error. PvmOk is the slay outcome, anything below zero is the "we need to talk" outcome. 😭

---

✨ DESCRIPTION ✨

so the routine pvm_precv blocks the process until a message with label msgtag has arrived from tid. she is not leaving, she is not moving on, she is waiting — patiently, dramatically, until it's her moment. then pvm_precv places the contents of the message in the supplied buffer, buf, up to a maximum length of len * (size of data type).

pvm_precv can receive messages sent by pvm_psend, pvm_send, pvm_mcast, or pvm_bcast. four senders, all welcome, she's very inclusive. 💖

A -1 in msgtag or tid matches anything. and this is where it gets fun, because that gives you the following options:

• 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.
• If msgtag = -1 and tid is defined by the user, then pvm_precv will accept any message that is sent from process tid.
• If tid = -1 and msgtag = -1, then pvm_precv will accept any message from any process.

no filter, no cap, she'll take anyone's message. wildcard energy fr fr. 🃏

---

🧚 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]

okay so that note is so important, like lowkey the whole vibe: datatype is doing length math, not transforming your data. raw bytes, bestie, 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 the same data types specified for unpack should be used. consistency is the vibe check. 🫶

---

💫 message order, the PVM guarantee 💫

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. Moreover, if both messages arrive before task 2 does a receive, then a wildcard receive will always return message A.

so like, first come first served, no line-jumping, no chaos. the queue is respected. 👑

---

⭐ the return value ⭐

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

---

🛏️ blocking behavior 🛏️

pvm_precv is blocking which means the routine waits until a message matching the user specified tid and msgtag arrives at the local pvmd. If the message has already arrived then pvm_precv returns immediately with the message.

so she waits if she has to, but if the message is already sitting there? instant. no waiting room. 💅

---

🌈 and one more thing 🌈

pvm_precv does not affect the state of the current receive message buffer (created by the other receive functions).

she minds her own business. she does not touch your other buffers. respectful queen. 🎀

---

🚨 WARNINGS 🚨

bestie, this part matters, don't scroll past it. 😤

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.

like, in those specific versions, these two worlds do NOT mix. psend/precv is one clique, send/recv/nrecv/trecv is the other. do not cross the streams. 💀

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 on generic Unix it's all good, everyone talks to everyone. elsewhere? read the room.

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

one shared tag space, two senders. if you wildcard it, you might grab the wrong girl's message. be specific, be safe. 🙈

---

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

see how Fortran said -1 for tid? wildcard from anyone. main character move. ✨

---

💀 ERRORS 💀

These error conditions can be returned by pvm_precv:

• PvmBadParam — giving an invalid tid, msgtag, or datatype. you gave her something she can't work with, and she's telling you.
• PvmSysErr — pvmd not responding. the daemon ghosted. it's giving silence. 😭

---

🦋 SEE ALSO 🦋

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

go read those too, they're the friends of this function and honestly they're all connected. iykyk. 💜

---

that's the whole page, bestie — written 15 March, 1994, straight out of PVM Version 3.4. go forth, receive your messages directly into your buffer, and slay. 🎀✨💅