PUTINFO(3PVM)

✨ NAME ✨

pvm_putinfo, pvm_recvinfo, pvm_getmboxinfo, pvm_delinfo — bestie, these four are your lil' crew for storing and retrieving messages in the global mailbox. It's a whole group chat for your PVM tasks. 💌

---

🫶 SYNOPSIS 🫶

C:

C    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:

     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, a.k.a. the class name. Any null-terminated string, slay. ✨
• index — the other half of the database key, the class index. Gotta be >= 0. Default index = 0.
• flags — your user-specified options, bestie. (the whole tea is below 👇)
• bufid — handle of the message buffer you're putting in the database, or the message that came back out. A returned bufid < 0 means error, no cap. 😭
• info — the resulting status code.
• pattern — a GNU regular expression (pattern) that gets matched against names in the mailbox database. Also, and this is iconic, the singular "*" will match on all names. 💫
• nclasses — how many classes matched the pattern.
• classes — array of pvmmboxinfo mailbox entries that matched 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 information to other PVM tasks. Example? Advertise the names or locations of services. Another example? Advertise a common "context" that two tasks can communicate on. It's giving matchmaking, honestly. 💖

The database entries are PVM messages, and they're keyed by a user specified name plus an optional index value. The name can be any null-terminated string and the index is a non-negative integer. The index value is assigned by PVM and it's what uniquely identifies one of multiple named instances inside the database. 🔑

Entries are "owned" by the task that created them. When the owner task exits, its entry is automatically removed from the database — unless that entry was created with the flag PvmMboxPersistent. 👑

And when a task exits and leaves an entry behind in the mailbox, the owner tid of that entry gets marked as zero (0) to show there's no longer an active owner task. Rest in peace, king. 🕊️

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

The following options are added together as the flags parameter to pvm_putinfo:

• PvmMboxDefault — inserts the entry as the only named instance for a given name. This entry may only be modified and deleted by its owner, and it's automatically deleted when its owner exits.
• PvmMboxPersistent — the entry stays in the database even when the owner task exits. (Entries get removed from the database when PVM is halted or a reset is issued from the console. That's the fine print. 📜)
• PvmMboxMultiInstance — permits multiple entry instances of the same name. PVM will assign an index key to each instance. ✨
• PvmMboxOverWritable — permits other tasks to overwrite and delete this database entry. Bold of you. 💅
• 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. And if index is greater than 0, then the mailbox must also have been created with the PvmMboxMultiInstance flag set. So many rules but we love a structured queen. 👑

pvm_recvinfo operates just like a pvm_recv() except the message is coming from the database. You should unpack the message 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. A 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 an exact match isn't found. 🔍
• PvmMboxFirstAvail — the first entry in <name> with an index greater than or equal to the specified index parameter is returned. Fun fact bestie: PvmMboxFirstAvail with index = 0 will produce the same results as using PvmMboxDefault. 🎯
• PvmMboxReadAndDelete — return the entry and delete it 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 doesn't exist, and will return PvmDenied if the record exists but may not be deleted. Double homicide. 💀

pvm_delinfo deletes the database entry specified by the key <name, index>. It returns PvmOK if the record was deleted, PvmNotFound if the record doesn't exist, or PvmDenied if you try to remove a "locked" record. 🔒

There are no flags presently specified for pvm_delinfo. (Not a single one. We respect the minimalism. 🤷)

pvm_getmboxinfo returns an array of pvmmboxinfo for all class names in the database. Programs that clean up the database use this, and so do applications trying to find out what's available. classes returns a pointer to the array allocated by libpvm and freed on the next call to pvm_getmboxinfo. 🧹✨

The Fortran function returns information on one entry per call. So if you call it repeatedly until an info value of PvmNotFound comes back, all entries matching the given pattern will have been returned. And if you want a new pattern, calling pvmfgetnames() with info = -1 will reset the entry name list and obtain a new list for the given pattern. 🔁

---

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

(Not me leaving the Fortran examples exactly as the page left them. The vibes are authentic. 🙈)

---

💀 ERRORS 💀

These are the error conditions that 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. She's not here. 🫥
• 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)

---

That's the whole page, bestie!! 💖 This one's from PVM Version 3.4, dated 22 May, 1997 — old enough to be vintage but the mailbox never goes out of style. ✨🎀 Go advertise your services, you main character. 💅🌈