PUTINFO(3PVM) PVM Version 3.4 PUTINFO(3PVM)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 commu‐
nicate.
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 auto‐
matically 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 success‐
fully 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(
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 com‐
ing from the database. The message should be unpacked after pvm_recv‐
info(). 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 PvmNot‐
Found 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 PvmMboxDe‐
fault.
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 Pvm‐
Denied 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 ALSOpvm_initsend(3PVM), pvm_getsbuf(3PVM), pvm_pack(3PVM),
22 May, 1997 PUTINFO(3PVM)
