18.2.34. PMIx_Notify_event

PMIx_Notify_event — Report an event for distribution to any registered event handlers.

18.2.34.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Notify_event(pmix_status_t status,
                                const pmix_proc_t *source,
                                pmix_data_range_t range,
                                const pmix_info_t info[], size_t ninfo,
                                pmix_op_cbfunc_t cbfunc, void *cbdata);

18.2.34.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after a successful foo.init() ...
# the source is a Python ``pmix_proc_t`` dictionary
src = {'nspace': "testnspace", 'rank': 0}
# the directives is a list of Python ``pmix_info_t`` dictionaries
pyinfo = [{'key': PMIX_EVENT_NON_DEFAULT,
           'value': {'value': True, 'val_type': PMIX_BOOL}}]
rc = foo.notify_event(PMIX_ERR_PROC_ABORTED, src, PMIX_RANGE_NAMESPACE, pyinfo)

18.2.34.2. INPUT PARAMETERS

status: The pmix_status_t code identifying the event being reported. Callers are not constrained to the status values defined by the PMIx Standard; any integer value may be used, allowing applications to define and notify their own internal events.
source: Pointer to a pmix_proc_t identifying the process that generated the event. A NULL value indicates that the caller itself is the source of the event.
range: A pmix_data_range_t value specifying the range across which the event is to be delivered (see RANGE).
info: Pointer to an array of pmix_info_t(5) structures provided by the event generator to pass any additional information about the event — for example, the processes affected by the event, its nature, and its severity (see DIRECTIVES). The precise contents depend on the event generator. A NULL value is supported when no additional information is provided.
ninfo: Number of elements in the info array.

The blocking behavior is selected by the callback parameters:

cbfunc: Callback function of type pmix_op_cbfunc_t to be invoked upon completion of the notification’s local actions. If cbfunc is NULL, the call is treated as blocking and the result of the operation is returned in the function’s status code.
cbdata: Opaque pointer that is passed, unmodified, to cbfunc.

18.2.34.3. DESCRIPTION

Report an event so that it can be distributed to any registered event handlers according to the specified range. PMIx_Notify_event may be called by any PMIx process — application clients, tools, PMIx servers, and host environment (SMS) daemons alike.

A client application calls this function to notify the resource manager and/or other processes of an event it encountered. It may also be used to asynchronously notify other parts of the caller’s own process — for example, allowing one library to signal another when it has completed initialization — by using a range of PMIX_RANGE_PROC_LOCAL. A PMIx server calls this function to report events it has detected, and host SMS daemons call it to pass events down to the embedded PMIx server for delivery to local clients and for the host’s own registered handlers.

When cbfunc is non-NULL this is a non-blocking call: it returns immediately and cbfunc is invoked once the notification’s local actions are complete. At that point any messages required to carry the notification (e.g., to the local PMIx server) will have been queued, but may not yet have been transmitted. When cbfunc is NULL the call blocks and the result is returned directly.

A successful return reflects only that the request was accepted (or completed) locally; it does not indicate the success or failure of delivering the event to any recipient.

As with all non-blocking PMIx APIs, the caller must keep the source and info arrays valid until cbfunc is invoked — the sole purpose of the callback is to indicate when the input data is no longer required.

18.2.34.4. RANGE

The range argument constrains which processes are eligible to receive the event notification:

PMIX_RANGE_PROC_LOCAL — restrict delivery to the caller’s own process; the event is not sent to the local PMIx server.
PMIX_RANGE_LOCAL — deliver only to processes on the same local node as the event generator.
PMIX_RANGE_NAMESPACE — deliver only to processes in the same namespace as the source.
PMIX_RANGE_SESSION — deliver to all processes in the session.
PMIX_RANGE_GLOBAL — deliver to all processes.
PMIX_RANGE_CUSTOM — deliver to a set of processes specified in the info array (see the PMIX_EVENT_CUSTOM_RANGE directive).
PMIX_RANGE_RM — the event is intended for the host resource manager.
PMIX_RANGE_UNDEF — no range was specified; PMIX_RANGE_INVALID denotes an invalid value.

18.2.34.5. DIRECTIVES

The following attributes are required to be supported by all PMIx libraries and will be passed, when relevant, to all invoked handlers:

PMIX_EVENT_NON_DEFAULT (bool) — the event is not to be delivered to default event handlers, only to those that explicitly registered for it.
PMIX_EVENT_CUSTOM_RANGE (pmix_data_array_t*) — array of pmix_proc_t identifying the processes that are to receive the notification when a range of PMIX_RANGE_CUSTOM is specified.
PMIX_EVENT_DO_NOT_CACHE (bool) — instruct the PMIx server not to cache the event for later delivery to processes that have not yet started.
PMIX_EVENT_PROXY (pmix_proc_t*) — the process that relayed the event on behalf of the original source.
PMIX_EVENT_TEXT_MESSAGE (char*) — a human-readable text message describing the event, suitable for reporting to the user.
PMIX_EVENT_TIMESTAMP (time_t) — the system time at which the associated event occurred.
PMIX_EVENT_STAYS_LOCAL (bool) — the event is not to be passed up to the host environment. Used together with a custom range to also indicate a range of “local” and to prevent infinite notification loops with the host.
PMIX_EVENT_SILENT_TERMINATION (bool) — suppress the event that is otherwise generated when a job terminates normally. This is typically supplied in a job’s launch-time information (e.g., to PMIx_Spawn(3)) rather than passed to PMIx_Notify_event directly.

Host environments that implement support for PMIx event notification are required to provide the following attributes for all events they generate:

PMIX_EVENT_AFFECTED_PROC (pmix_proc_t*) — single process affected by the event.
PMIX_EVENT_AFFECTED_PROCS (pmix_data_array_t*) — array of pmix_proc_t identifying the processes affected by the event.

The following attributes may optionally be included by a host environment to indicate its intended response to an environmental or SMS event:

PMIX_EVENT_TERMINATE_SESSION (bool) — the RM intends to terminate the session.
PMIX_EVENT_TERMINATE_JOB (bool) — the RM intends to terminate the entire job.
PMIX_EVENT_TERMINATE_NODE (bool) — the RM intends to terminate all processes on the affected node.
PMIX_EVENT_TERMINATE_PROC (bool) — the RM intends to terminate just the affected process(es).
PMIX_EVENT_ACTION_TIMEOUT (int) — the time, in seconds, before the RM will execute the indicated termination action.

18.2.34.6. RETURN VALUE

For the non-blocking form (a non-NULL cbfunc), a return of PMIX_SUCCESS indicates only that the request was accepted for processing and the final status will be delivered to cbfunc. For the blocking form (NULL cbfunc), the returned status reflects the result of the local operation.

PMIX_SUCCESS — the request was accepted; for a non-blocking call, cbfunc will be invoked upon completion.
PMIX_OPERATION_SUCCEEDED — the request was processed immediately and successfully; cbfunc will not be called.
PMIX_ERR_UNREACH — the caller is not connected to its PMIx server and the requested range requires reaching it.
PMIX_ERR_NOT_AVAILABLE — the operation cannot be serviced because the library’s progress engine has been stopped.
PMIX_ERR_INIT — the PMIx library has not been initialized.
PMIX_ERR_NOMEM — the library was unable to allocate memory to process the request.

Note that a successful return does not reflect the success or failure of delivering the event to any recipient. Any other negative value indicates an appropriate error condition. PMIx error constants are defined in pmix_common.h.

18.2.34.7. NOTES

The PMIx server library is not permitted to echo an event handed to it by its host back to that host. When a host delivers an event via this API, it is required to also deliver that event to all PMIx servers where the targeted processes are currently running — or might run in the future — since events are cached by the PMIx server library for delivery to processes that have not yet started (unless PMIX_EVENT_DO_NOT_CACHE is specified).

Event handlers are registered with PMIx_Register_event_handler(3) and removed with PMIx_Deregister_event_handler(3).