1PUTINFO(3PVM) PVM Version 3.4 PUTINFO(3PVM)
2
6 pvm_putinfo, pvm_recvinfo, pvm_getmboxinfo, pvm_delinfo - Store and
7 retrieve messages in global mailbox.
8
11 C int index = pvm_putinfo( char *name, int bufid, int flags )
12 int bufid = pvm_recvinfo( char *name, int index, int flags )
13 int info = pvm_delinfo( char *name, int index, int flags )
14 int info = pvm_getmboxinfo( char *pattern, int *nclasses,
15 struct pvmmboxinfo **classes )
16 struct pvmmboxinfo {
18 char *mi_name; /* class name */
19 int mi_nentries; /* # of entries for this class */
20 int *mi_indices; /* mbox entry indices */
21 int *mi_owners; /* mbox entry owner tids */
22 int *mi_flags; /* mbox entry flags */
23 };
24 Fortran
26 call pvmfputinfo( name, bufid, flags, index )
27 call pvmfrecvinfo( name, index, flags, bufid )
28 call pvmfdelinfo( name, index, flags, info )
29 call pvmfgetmboxinfo( pattern, name, nclasses, nentries,
30 index, owner, flags, info )
31
35 name
36 Database key (class name), any null-terminated string.
37 index
39 Database key (class index), >= 0. Default index = 0.
40 flags
42 User specified options. (see below)
43 bufid
45 Handle of message buffer to put in database, or message
46 returned. A returned bufid < 0 indicates an error.
47 info
49 Resulting status code.
50 pattern
52 GNU regular expression (pattern) to match on names in mailbox
53 database. Additionally, the singular "*" will match on all
54 names.
55 nclasses
57 Number of classes matching pattern.
58 classes
60 Array of pvmmboxinfo mailbox entries matching pattern.
61 nentries
63 Number of entries for a given class.
64 owner
66 Task id that inserted entry into mailbox database.
67
69 These functions implement a "message mailbox" database that can be used
70 by PVM tasks to advertise information to other PVM tasks. An example
71 would be to advertise names or locations of services. Another example
72 would be to advertise a common "context" on which two tasks may commu‐
73 nicate.
74 The database entries are PVM messages keyed by a user specified name
76 and an optional index value. The name may be any null-terminated
77 string and the index a non-negative integer. The index value is
78 assigned by PVM and is used to uniquely identify one of multiple named
79 instances within the database.
80 Entries are "owned" by the task that created them. An entry is auto‐
82 matically removed from the database when the owner task exits unless
83 the database entry was created with flag PvmMboxPersistent.
84 When a task exits and leaves an entry in the mailbox, the owner tid of
86 that entry is marked as zero (0) to indicate that there is no longer an
87 active owner task.
88 pvm_putinfo inserts a record in the database, given a key and data
91 (message). It returns mailbox index number if the record is success‐
92 fully stored, PvmExists if a record with the given key already exists,
93 or PvmDenied if an attempt is made to overwrite a locked record.
94 The following options are added together as the flags parameter to
96 pvm_putinfo.
97 PvmMboxDefault
100 Inserts entry as the only named instance for a given name. This
101 entry may only be modified and deleted by its owner. It is
102 automatically deleted when its owner exits.
103 PvmMboxPersistent
106 Entry remains in the database when the owner task exits.
107 Entries are removed from the database when PVM is halted or a
108 reset is issued from the console.
109 PvmMboxMultiInstance
112 Permits multiple entry instances of the same name. PVM will
113 assign an index key to each instance.
114 PvmMboxOverWritable
117 Permits other tasks to overwrite and delete this database entry.
118 PvmMboxDirectIndex(
121 Performs an atomic delete and re-insert for the mailbox entry at
122 the given index. Valid index values for this macro are limited
123 to the range [ 0 .. PvmMboxMaxDirectIndex ). The given mailbox
124 entry must have been created with the PvmMboxOverWritable flag
125 set. If index is greater than 0, then the mailbox must also
126 have been created with the PvmMboxMultiInstance flag set.
127 pvm_recvinfo operates just like a pvm_recv() except the message is com‐
129 ing from the database. The message should be unpacked after pvm_recv‐
130 info(). Like pvm_recv, pvm_recvinfo returns a pointer to a message
131 buffer containing the record matching the key <name,index> from the
132 database. Returned value < 0 indicates an error.
133 The following options are added together as the flags parameter to
135 pvm_recvinfo.
136 PvmMboxDefault
139 Exact match on key <name, index> is returned. Returns PvmNot‐
140 Found if exact match not found.
141 PvmMboxFirstAvail
144 The first entry in <name> with index greater than or equal to
145 the specified index parameter is retuned. PvmMboxFirstAvail
146 with index = 0 will produce the same results as using PvmMboxDe‐
147 fault.
148 PvmMboxReadAndDelete
151 Return entry and delete from database. Task must be permitted
152 to do both read and delete otherwise an error will occur. bufid
153 returns PvmNotFound if entry does not exist and will return Pvm‐
154 Denied if the record exists but may not be deleted.
155 pvm_delinfo deletes database entry specified by the key <name, index>.
157 Returns PvmOK if the record was deleted, PvmNotFound if the record does
158 not exist, or PvmDenied if an attempt is made to remove a "locked"
159 record.
160 There are no flags presently specified for pvm_delinfo.
162 pvm_getmboxinfo returns an array of pvmmboxinfo for all class names in
164 the database. This is used, for example, by programs that clean up the
165 database or for applications to find out what is available. classes
166 returns a pointer to the array allocated by libpvm and freed on the
167 next call to pvm_getmboxinfo.
168 The Fortran function returns information on one entry per call. Thus,
170 if called repeatedly until an info value of PvmNotFound is returned,
171 all entries matching the given pattern will have been returned. If a
172 new pattern is desired, calling pvmfgetnames() with info = -1 will
173 reset the entry name list and obtain a new list for the given pattern.
174
177 C:
178 /*
179 * create and insert mailbox entry
180 */
181 sprintf( service, "Task_A_service" );
182 sprintf( message, "Greetings from task A." );
183 pvm_initsend( PvmDataDefault );
184 pvm_pkint( &mytid, 1, 1 );
185 pvm_pkint( &context, 1, 1 );
186 pvm_pkstr( message );
187 if (( pvm_putinfo( service, pvm_getsbuf(), PvmMboxDefault )) == PvmExists ){
188 printf( "can't register - service already running0 );
189 exit( -1 );
190 }
191 /*
194 * look for and retrieve specified mailbox
195 */
196 sprintf( service, "Task_A_service" );
197 if (( msg_buf = pvm_recvinfo(service, 0, PvmMboxFirstAvail )) >= 0 ){
198 pvm_setrbuf( msg_buf );
199 pvm_upkint( &their_tid, 1, 1 );
200 pvm_upkint( &their_context, 1, 1 );
201 pvm_upkstr( message );
202 }
203 Fortran:
205 we need the fortran examples...
206
211 The following error conditions can be returned by one or more of these
212 functions:
213 PvmBadParam
215 An invalid value was specified for bufid argument.
216 PvmNoSuchBuf
218 Message buffer bufid doesn't exist.
219 PvmNoMem
221 Libpvm is unable to allocate memory to pack data.
222 PvmExists
224 The requested key is already in use (pvm_putinfo).
225 PvmNotFound
227 The requested key does not exist (pvm_recvinfo, pvm_delinfo).
228 PvmDenied
230 The key is locked by another task and cannot be replaced or
231 deleted.
232
235 pvm_initsend(3PVM), pvm_getsbuf(3PVM), pvm_pack(3PVM),
236 22 May, 1997 PUTINFO(3PVM)