1ADDMHF(3PVM)                    PVM Version 3.4                   ADDMHF(3PVM)
2
3
4

NAME

6       pvm_addmhf, pvm_delmhf - Install or remove message-handler functions.
7
8

SYNOPSIS

10       C    int mhid = pvm_addmhf( int src, int tag, int ctx, int (*func)(int mid) )
11            int info = pvm_delmhf( int mhid )
12
13       Fortran   Not available
14
15

PARAMETERS

17       src    The tid of the sender.
18
19       tag    The tag sent with the message.
20
21       ctx    The context sent with the message.
22
23       func   Function to call when message received.
24
25       mhid   Message handler id.
26
27       info   Result code.
28
29       mid    Message buffer identifier for new active receive buffer.
30
31

DESCRIPTION

33       pvm_addmhf  specifies  a  function  that will be called whenever libpvm
34       copies in a message whose header fields of  src,  tag,  and  ctx  match
35       those provided to pvm_addmhf().
36
37       The src and tag fields may be left unspecified (wildcard) by setting to
38       -1.
39
40       The calling sequence of the message handler function is:
41
42            int handler( int mid )
43
44       Where mid is the bufid of the received message.  The  handler  function
45       can  be  used  to  unpack and process the received message buffer.  PVM
46       automatically saves the current send and receive buffers, so  the  han‐
47       dler need not worry about interfering with message buffers in the regu‐
48       lar program flow.  PVM also sets the  current  receive  buffer  to  the
49       received message (using pvm_setrbuf()) before invoking the message han‐
50       dler, so the message can be unpacked directly.  PVM will free this mes‐
51       sage  buffer  when  the message handler returns, if the handler has not
52       already done so.  But, any other message buffers created by the handler
53       routine should be freed using pvm_freebuf() before returning.
54
55       Note:  Operation in the message handler context is somewhat restricted.
56       The function may call some PVM functions, but not others.  For example,
57       it may compose and send a reply message as shown:
58
59            pvm_packf( "%+ %s", PvmDataDefault, "got your message" );
60            pvm_send( tid, tag );
61            pvm_freebuf( pvm_setsbuf( 0 ) );
62
63       or equivalently:
64
65            pvm_setsbuf( pvm_mkbuf( PvmDataDefault ) );
66            pvm_pkstr( "got your message" );
67            pvm_send( tid, tag );
68            pvm_freebuf( pvm_setsbuf( 0 ) );
69
70       but  is  not allowed to call certain other PVM communication functions,
71       such as multicast or receive.
72
73       pvm_addmhf returns the id number of the newly created  message  handler
74       if  successful;  this  number may be passed to pvm_delmhf to remove the
75       entry.  There is no guarantee to the ordering of id values returned  by
76       pvm_addmhf,  or to the order in which message handlers will be invoked.
77       PvmExists is returned if the handler already exists.
78
79       pvm_delmhf returns PvmOk if successful.  PvmBadParam if  pvm_delmhf  is
80       passed a negative id value.  PvmNotFound if the id value is not found.
81
82

EXAMPLES

84            /* Print a message when hosts are added to virtual machine */
85
86            int
87            hostAdded( int mid )
88            {
89                 int n;
90                 pvm_unpackf( "%d", &n );
91                 printf( "*** %d new hosts just added ***\n", n );
92            }
93
94            void
95            main()
96            {
97                 int src, tag, ctx;
98
99                 . . .
100
101                 src = -1;
102                 tag = 99;
103                 ctx = -1;
104
105                 pvm_addmhf( src, tag, ctx, hostAdded );
106                 pvm_notify( PvmHostAdd, 99, -1, (int *) NULL );
107
108                 . . .
109            }
110
111

ERRORS

113       The following error conditions can be returned by pvm_addmhf():
114
115       PvmExists
116              Can't insert as handler already exists with same (tag, ctx, src)
117              including "wild-cards" (those set to -1)
118
119       The following error conditions can be returned by pvm_delmhf():
120
121       PvmBadParam
122              Invalid (negative) mhid passed in.
123
124       PvmNotFound
125              Message handler mhid does not exist.
126

SEE ALSO

128       pvm_setrbuf(3PVM), pvm_setsbuf(3PVM), pvm_freebuf(3PVM)
129
130
131
132                                 1 April, 1997                    ADDMHF(3PVM)
Impressum