Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PUTINFO(3PVM)			PVM Version 3.4			 PUTINFO(3PVM)

NAME
       pvm_putinfo, pvm_recvinfo, pvm_getmboxinfo, pvm_delinfo - Store and re-
       trieve 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  re-
	      turned.  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 as-
       signed 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  au-
	      tomatically deleted when its owner exits.

       PvmMboxPersistent
	      Entry  remains  in  the database when the	owner task exits.  En-
	      tries are	removed	from the database when PVM is halted or	a  re-
	      set is issued from the console.

       PvmMboxMultiInstance
	      Permits multiple entry instances of the same name.  PVM will as-
	      sign 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 re-
       set 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),

				 22 May, 1997			 PUTINFO(3PVM)

NAME | SYNOPSIS | PARAMETERS | DESCRIPTION | EXAMPLES | ERRORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pvm_putinfo&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help