ADDMHF(3PVM) PVM Version 3.4 ADDMHF(3PVM)NAME
pvm_addmhf, pvm_delmhf - Install or remove message-handler functions.
SYNOPSIS
C int mhid = pvm_addmhf( int src, int tag, int ctx, int (*func)(int mid) )
int info = pvm_delmhf( int mhid )
Fortran Not available
PARAMETERS
src The tid of the sender.
tag The tag sent with the message.
ctx The context sent with the message.
func Function to call when message received.
mhid Message handler id.
info Result code.
mid Message buffer identifier for new active receive buffer.
DESCRIPTION
pvm_addmhf specifies a function that will be called whenever libpvm
copies in a message whose header fields of src, tag, and ctx match
those provided to pvm_addmhf().
The src and tag fields may be left unspecified (wildcard) by setting to
-1.
The calling sequence of the message handler function is:
int handler( int mid )
Where mid is the bufid of the received message. The handler function
can be used to unpack and process the received message buffer. PVM
automatically saves the current send and receive buffers, so the han‐
dler need not worry about interfering with message buffers in the regu‐
lar program flow. PVM also sets the current receive buffer to the
received message (using pvm_setrbuf()) before invoking the message han‐
dler, so the message can be unpacked directly. PVM will free this mes‐
sage buffer when the message handler returns, if the handler has not
already done so. But, any other message buffers created by the handler
routine should be freed using pvm_freebuf() before returning.
Note: Operation in the message handler context is somewhat restricted.
The function may call some PVM functions, but not others. For example,
it may compose and send a reply message as shown:
pvm_packf( "%+ %s", PvmDataDefault, "got your message" );
pvm_send( tid, tag );
pvm_freebuf( pvm_setsbuf( 0 ) );
or equivalently:
pvm_setsbuf( pvm_mkbuf( PvmDataDefault ) );
pvm_pkstr( "got your message" );
pvm_send( tid, tag );
pvm_freebuf( pvm_setsbuf( 0 ) );
but is not allowed to call certain other PVM communication functions,
such as multicast or receive.
pvm_addmhf returns the id number of the newly created message handler
if successful; this number may be passed to pvm_delmhf to remove the
entry. There is no guarantee to the ordering of id values returned by
pvm_addmhf, or to the order in which message handlers will be invoked.
PvmExists is returned if the handler already exists.
pvm_delmhf returns PvmOk if successful. PvmBadParam if pvm_delmhf is
passed a negative id value. PvmNotFound if the id value is not found.
EXAMPLES
/* Print a message when hosts are added to virtual machine */
int
hostAdded( int mid )
{
int n;
pvm_unpackf( "%d", &n );
printf( "*** %d new hosts just added ***\n", n );
}
void
main()
{
int src, tag, ctx;
. . .
src = -1;
tag = 99;
ctx = -1;
pvm_addmhf( src, tag, ctx, hostAdded );
pvm_notify( PvmHostAdd, 99, -1, (int *) NULL );
. . .
}
ERRORS
The following error conditions can be returned by pvm_addmhf():
PvmExists
Can't insert as handler already exists with same (tag, ctx, src)
including "wild-cards" (those set to -1)
The following error conditions can be returned by pvm_delmhf():
PvmBadParam
Invalid (negative) mhid passed in.
PvmNotFound
Message handler mhid does not exist.
SEE ALSOpvm_setrbuf(3PVM), pvm_setsbuf(3PVM), pvm_freebuf(3PVM)
1 April, 1997 ADDMHF(3PVM)
