PUTINFO(3PVM)

PVM Version 3.4 · bestie we're reading PUTINFO(3PVM) today 💌 it's the man page for the PVM mailbox situation, and yes it's as cute as it sounds (it's a database of messages, it's giving pigeonhole but make it distributed)

---

🎀 NAME 🎀

pvm_putinfo, pvm_recvinfo, pvm_getmboxinfo, pvm_delinfo — store and retrieve messages in global mailbox. that's it. that's the whole vibe 💅

---

✨ SYNOPSIS ✨

C bestie:

int index = pvm_putinfo( char *name, int bufid, int flags )
int bufid = pvm_recvinfo( char *name, int index, int flags )
int info = pvm_delinfo( char *name, int index, int flags )
int info = pvm_getmboxinfo( char *pattern, int *nclasses,
                            struct pvmmboxinfo **classes )

struct pvmmboxinfo {
   char *mi_name;                /* class name */
   int   mi_nentries;            /* # of entries for this class */
   int  *mi_indices;             /* mbox entry indices */
   int  *mi_owners;              /* mbox entry owner tids */
   int  *mi_flags;               /* mbox entry flags */
};

Fortran bestie:

call pvmfputinfo( name, bufid, flags, index )
call pvmfrecvinfo( name, index, flags, bufid )
call pvmfdelinfo( name, index, flags, info )
call pvmfgetmboxinfo( pattern, name, nclasses, nentries,
                      index, owner, flags, info )

---

🫶 PARAMETERS 🫶

• name — the database key (aka the class name), and it can be literally any null-terminated string you want. go off.
• index — the database key (aka the class index), and it's >= 0. default index = 0.
• flags — your user-specified options, babes. (peep below 👇)
• bufid — handle of the message buffer you're putting in the database, or the message you got back. a returned bufid < 0 means something went wrong, sorry bestie 😭
• info — the resulting status code.
• pattern — a GNU regular expression (pattern) to match on names in the mailbox database. plus, the singular "*" will match on all names. iconic.
• nclasses — number of classes matching the pattern.
• classes — array of pvmmboxinfo mailbox entries matching the pattern.
• nentries — number of entries for a given class.
• owner — the task id that inserted the entry into the mailbox database.

---

💖 DESCRIPTION 💖

okay so these functions implement a "message mailbox" database that PVM tasks can use to advertise info to other PVM tasks. example? advertising the names or locations of services. another example? advertising a common "context" that two tasks can communicate on. it's giving matchmaker, fr fr.

The database entries are PVM messages keyed by a user specified name and an optional index value. The name may be any null-terminated string and the index a non-negative integer. The index value is assigned by PVM and is used to uniquely identify one of multiple named instances within the database. one name, many instances, no cap.

Entries are "owned" by the task that created them. An entry is automatically removed from the database when the owner task exits — unless the database entry was created with flag PvmMboxPersistent. so if you want it to survive, say so.

When a task exits and leaves an entry in the mailbox, the owner tid of that entry is marked as zero (0) to indicate that there is no longer an active owner task. ghosted, but make it a tid 🫥

pvm_putinfo inserts a record in the database, given a key and data (message). It returns the mailbox index number if the record is successfully stored, PvmExists if a record with the given key already exists, or PvmDenied if an attempt is made to overwrite a locked record.

The following options are added together as the flags parameter to pvm_putinfo. add them, stack them, whatever, just don't lose track of them 💅

• PvmMboxDefault — inserts the entry as the only named instance for a given name. This entry may only be modified and deleted by its owner. It is automatically deleted when its owner exits. possessive in a healthy way.
• PvmMboxPersistent — the entry remains in the database when the owner task exits. Entries are removed from the database when PVM is halted or a reset is issued from the console. so it outlives you, but not the whole party.
• PvmMboxMultiInstance — permits multiple entry instances of the same name. PVM will assign an index key to each instance. clone era.
• PvmMboxOverWritable — permits other tasks to overwrite and delete this database entry. sharing is caring.
• PvmMboxDirectIndex( index ) — performs an atomic delete and re-insert for the mailbox entry at the given index. Valid index values for this macro are limited to the range [ 0 .. PvmMboxMaxDirectIndex ). The given mailbox entry must have been created with the PvmMboxOverWritable flag set. If index is greater than 0, then the mailbox must also have been created with the PvmMboxMultiInstance flag set. read that twice bestie, the constraints are real.

pvm_recvinfo operates just like a pvm_recv() except the message is coming from the database. The message should be unpacked after pvm_recvinfo(). Like pvm_recv, pvm_recvinfo returns a pointer to a message buffer containing the record matching the key <name,index> from the database. Returned value < 0 indicates an error.

The following options are added together as the flags parameter to pvm_recvinfo.

• PvmMboxDefault — exact match on key <name, index> is returned. Returns PvmNotFound if exact match not found. no substitutes, no swaps.
• PvmMboxFirstAvail — the first entry in <name> with index greater than or equal to the specified index parameter is retuned. PvmMboxFirstAvail with index = 0 will produce the same results as using PvmMboxDefault. (yes the manpage says "retuned", we love a typo that ate 💀)
• PvmMboxReadAndDelete — return the entry and delete from the database. The task must be permitted to do both read and delete, otherwise an error will occur. bufid returns PvmNotFound if the entry does not exist and will return PvmDenied if the record exists but may not be deleted. read it and yeet it, but only if you're allowed.

pvm_delinfo deletes the database entry specified by the key <name, index>. Returns PvmOK if the record was deleted, PvmNotFound if the record does not exist, or PvmDenied if an attempt is made to remove a "locked" record.

There are no flags presently specified for pvm_delinfo. none. zero. a flagless queen.

pvm_getmboxinfo returns an array of pvmmboxinfo for all class names in the database. This is used, for example, by programs that clean up the database or for applications to find out what is available. classes returns a pointer to the array allocated by libpvm and freed on the next call to pvm_getmboxinfo. so peek while you can, bestie, it gets recycled.

The Fortran function returns information on one entry per call. Thus, if called repeatedly until an info value of PvmNotFound is returned, all entries matching the given pattern will have been returned. If a new pattern is desired, calling pvmfgetnames() with info = -1 will reset the entry name list and obtain a new list for the given pattern. one at a time, like a lil conveyor belt 🍓

---

🔥 EXAMPLES 🔥

C:

/*
*  create and insert mailbox entry
*/
sprintf( service, "Task_A_service" );
sprintf( message, "Greetings from task A." );
pvm_initsend( PvmDataDefault );
pvm_pkint( &mytid, 1, 1 );
pvm_pkint( &context, 1, 1 );
pvm_pkstr( message );
if (( pvm_putinfo( service, pvm_getsbuf(), PvmMboxDefault )) == PvmExists ){
     printf( "can't register - service already running0 );
     exit( -1 );
}

/*
*  look for and retrieve specified mailbox
*/
sprintf( service, "Task_A_service" );
if (( msg_buf = pvm_recvinfo(service, 0, PvmMboxFirstAvail )) >= 0 ){
     pvm_setrbuf( msg_buf );
     pvm_upkint( &their_tid, 1, 1 );
     pvm_upkint( &their_context, 1, 1 );
     pvm_upkstr( message );
}

Fortran:

we need the fortran examples...

ngl the Fortran example section is literally just that one line in the original. we're not making it up, we're just reporting the situation 🫠

---

😭 ERRORS 😭

The following error conditions can be returned by one or more of these functions:

• PvmBadParam — an invalid value was specified for the bufid argument.
• PvmNoSuchBuf — message buffer bufid doesn't exist.
• PvmNoMem — libpvm is unable to allocate memory to pack data.
• PvmExists — the requested key is already in use (pvm_putinfo).
• PvmNotFound — the requested key does not exist (pvm_recvinfo, pvm_delinfo).
• PvmDenied — the key is locked by another task and cannot be replaced or deleted.

---

🌈 SEE ALSO 🌈

• pvm_initsend(3PVM)
• pvm_getsbuf(3PVM)
• pvm_pack(3PVM)

---

and that's the whole page bestie 💖 this was PUTINFO(3PVM) from the PVM Version 3.4 manual, dated 22 May, 1997 — yeah it's old, but the mailbox still slays. go advertise your services, periodt 💅✨🦋