ADDMHF(3PVM)

💖 ADDMHF — pvm_addmhf, pvm_delmhf 💖

okay so bestie, welcome to PVM Version 3.4, and today we're talking about the two functions that let you install and remove message-handler functions: pvm_addmhf and pvm_delmhf. It's giving "I want a lil callback whenever a message shows up" energy and honestly? Iconic. 🎀

---

✨ SYNOPSIS ✨

C    int mhid = pvm_addmhf( int src, int tag, int ctx, int (*func)(int mid) )
     int info = pvm_delmhf( int mhid )

Fortran   Not available

so the C girlies are eating good, and the Fortran girlies... are not. Fortran: Not available. 💀 That's it, that's the whole sentence. No Fortran for you.

---

🌸 PARAMETERS 🌸

• src — the tid of the sender. like, who sent it, bestie.
• tag — the tag that got sent along with the message.
• ctx — the context that got sent along with the message.
• func — the function you want called when the message arrives. your lil callback bae 🫶
• mhid — the message handler id. this is the receipt, keep it.
• info — the result code. basically the vibe check on whether it worked.
• mid — the message buffer identifier for the new active receive buffer.

---

💅 DESCRIPTION 💅

So pvm_addmhf lets you specify a function that gets called whenever libpvm copies in a message whose header fields of src, tag, and ctx match the ones you handed to pvm_addmhf(). like a little matching game but make it networking. ✨

The src and tag fields may be left unspecified (wildcard) by setting to -1. yes bestie, -1 is the wildcard. it matches everything. main character energy fr fr.

The calling sequence of the message handler function is:

int handler( int mid )

Where mid is the bufid of the received message. The handler function can be used to unpack and process the received message buffer. PVM automatically saves the current send and receive buffers, so the handler need not worry about interfering with message buffers in the regular program flow. PVM also sets the current receive buffer to the received message (using pvm_setrbuf()) before invoking the message handler, so the message can be unpacked directly. PVM will free this message buffer when the message handler returns, if the handler has not already done so. But, any other message buffers created by the handler routine should be freed using pvm_freebuf() before returning. no cap, clean up after yourself. 🧹

Note: Operation in the message handler context is somewhat restricted. The function may call some PVM functions, but not others. lowkey this is the part where you have to be careful, bestie.

For example, it may compose and send a reply message as shown:

pvm_packf( "%+ %s", PvmDataDefault, "got your message" );
pvm_send( tid, tag );
pvm_freebuf( pvm_setsbuf( 0 ) );

or equivalently:

pvm_setsbuf( pvm_mkbuf( PvmDataDefault ) );
pvm_pkstr( "got your message" );
pvm_send( tid, tag );
pvm_freebuf( pvm_setsbuf( 0 ) );

but is not allowed to call certain other PVM communication functions, such as multicast or receive. yeah. not those. don't do it. 🙈

pvm_addmhf returns the id number of the newly created message handler if successful; this number may be passed to pvm_delmhf to remove the entry. There is no guarantee to the ordering of id values returned by pvm_addmhf, or to the order in which message handlers will be invoked. so don't come for me about ordering, okay? it's giving chaos and we accept it. 😭

PvmExists is returned if the handler already exists.

pvm_delmhf returns PvmOk if successful. PvmBadParam if pvm_delmhf is passed a negative id value. PvmNotFound if the id value is not found.

---

🦋 EXAMPLES 🦋

/* Print a message when hosts are added to virtual machine */

int
hostAdded( int mid )
{
     int n;
     pvm_unpackf( "%d", &n );
     printf( "*** %d new hosts just added ***\n", n );
}

void
main()
{
     int src, tag, ctx;

     . . .

     src = -1;
     tag = 99;
     ctx = -1;

     pvm_addmhf( src, tag, ctx, hostAdded );
     pvm_notify( PvmHostAdd, 99, -1, (int *) NULL );

     . . .
}

see how src and ctx are -1 (wildcards) but tag is 99? that's the whole trick bestie. match on tag, wildcard the rest, and let hostAdded do its lil printf moment. slay. 💖

---

🔥 ERRORS 🔥

The following error conditions can be returned by pvm_addmhf():

• PvmExists — Can't insert as handler already exists with same (tag, ctx, src) including "wild-cards" (those set to -1)

The following error conditions can be returned by pvm_delmhf():

• PvmBadParam — Invalid (negative) mhid passed in.
• PvmNotFound — Message handler mhid does not exist.

fr fr read these. PvmExists catches you when you try to double-register a handler with the same (tag, ctx, src), and yes that includes the -1 wildcards. PvmBadParam means you sent a negative mhid (why). PvmNotFound means that id just isn't in the building. 💀

---

👑 SEE ALSO 👑

• pvm_setrbuf(3PVM)
• pvm_setsbuf(3PVM)
• pvm_freebuf(3PVM)

---

and that's the whole page babes — this was ADDMHF(3PVM) from PVM Version 3.4, dated 1 April, 1997. yes, April Fools' Day, and no, the wildcard -1 is not a prank. go forth and handle your messages. periodt. 💅✨🦋