bionic (3) pvm_notify.3PVM.gz

NAME

       pvm_notify - Request notification of PVM event such as host failure.

SYNOPSIS

       C    int info = pvm_notify( int what, int msgtag, int cnt, int *tids )

       Fortran   call pvmfnotify( what, msgtag, cnt, tids, info )

PARAMETERS

       what    Type of event to trigger the notification.  Presently one of:
                    Value               Meaning
                    PvmTaskExit         Task exits or is killed
                    PvmHostDelete       Host is deleted or crashes
                    PvmHostAdd          New host is added

       msgtag  Message tag to be used in notification.

       cnt     For  PvmTaskExit  and  PvmHostDelete,  specifies  the  length of the tids array.  For PvmHostAdd,
               specifies the number of times to notify.

       tids    For PvmTaskExit and PvmHostDelete, an array of length cnt of task or pvmd  TIDs  to  be  notified
               about.  The array is not used with the PvmHostAdd option.

       info    Integer status code returned by the routine.  Values less than zero indicate an error.

DESCRIPTION

       The routine pvm_notify requests PVM to notify the caller on detecting certain events.  One or more notify
       messages (see below) are sent by PVM back to the calling task.  The messages have tag msgtag supplied  to
       notify.

       The notification messages have the following format:

       PvmTaskExit
              One notify message for each TID requested.  The message body contains a single TID of exited task.

       PvmHostDelete
              One  notify message for each TID requested.  The message body contains a single pvmd-TID of exited
              pvmd.

       PvmHostAdd
              cnt notify messages are sent, one each time the local pvmd's host table is updated.   The  message
              body  contains  an  integer  length  followed by a list of pvmd-TIDs of new pvmds.  The counter of
              PvmHostAdd messages yet to be sent is replaced by successive calls to  pvm_notify.   Specifying  a
              cnt of -1 turns on PvmHostAdd messages until a future notify; a count of zero disables them.

       TIDs in the notify messages are packed as integers.

       The  calling  task  is  responsible  for receiving messages with the specified tag and taking appropriate
       action.

       Future versions of PVM may expand the list of available notification events.

EXAMPLES

       C:
            info = pvm_notify( PvmTaskExit, 9999, ntask, tids );

       Fortran:
            CALL PVMFNOTIFY( PVMHOSTDELETE, 1111, NUMHOSTS, DTIDS, INFO )

       To "cancel" a notify request in PVM,  the  pvm_notify  routine  can  be  re-invoked  with  an  additional
       PvmNotifyCancel  flag  in  the what argument.  The remaining arguments to this cancelling invocation must
       match the original invocation exactly, aside from the additional PvmNotifyCancel which can be added(+) or
       OR-ed(|) to the what argument:

            pvm_notify( PvmTaskExit, 9999, ntask, tids );

            . . .

            pvm_notify( PvmTaskExit | PvmNotifyCancel, 9999, ntask, tids );

       Note  that  when a notify is cancelled, the notify message is delivered, as if the given event (i.e. task
       exit, host add or delete) had occurred.

ERRORS

       PvmSysErr
              pvmd not responding.

       PvmBadParam
              giving an invalid argument value.

SEE ALSO

       pvm_tasks(3PVM), pvm_config(3PVM)

                                                31 January, 1994                                    NOTIFY(3PVM)