NAME¶
pvm_putinfo, pvm_recvinfo, pvm_getmboxinfo, pvm_delinfo - Store and retrieve
messages in global mailbox.
SYNOPSIS¶
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
-
Database key (class name), any null-terminated string.
- index
-
Database key (class index), >= 0. Default index = 0.
- flags
-
User specified options. (see below)
- bufid
-
Handle of message buffer to put in database, or message returned. A returned
bufid < 0 indicates an error.
- info
-
Resulting status code.
- pattern
-
GNU regular expression (pattern) to match on names in mailbox database.
Additionally, the singular "*" will match on all names.
- nclasses
-
Number of classes matching pattern.
- classes
-
Array of pvmmboxinfo mailbox entries matching pattern.
- nentries
-
Number of entries for a given class.
- owner
-
Task id that inserted entry into mailbox database.
DESCRIPTION¶
These functions implement a "message mailbox" database that can be
used by PVM tasks to advertise information to other PVM tasks. An example
would be to advertise names or locations of services. Another example would be
to advertise a common "context" on which two tasks may communicate.
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.
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.
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.
pvm_putinfo inserts a record in the database, given a key and data
(message). It returns 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.
- PvmMboxDefault
- Inserts 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.
- PvmMboxPersistent
- 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.
- 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.
- 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.
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.
- 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.
- PvmMboxReadAndDelete
- Return entry and delete from database. Task must be permitted to do both
read and delete otherwise an error will occur. bufid returns PvmNotFound
if entry does not exist and will return PvmDenied if the record exists but
may not be deleted.
pvm_delinfo deletes 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.
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.
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.
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...
ERRORS¶
The following error conditions can be returned by one or more of these
functions:
- PvmBadParam
- An invalid value was specified for 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),