18.2.261. PMIx_server_IOF_deliver

PMIx_server_IOF_deliver — Pass forwarded I/O to the PMIx server library for distribution to its clients.

18.2.261.1. SYNOPSIS

#include <pmix_server.h>

pmix_status_t PMIx_server_IOF_deliver(const pmix_proc_t *source,
                                      pmix_iof_channel_t channel,
                                      const pmix_byte_object_t *bo,
                                      const pmix_info_t info[], size_t ninfo,
                                      pmix_op_cbfunc_t cbfunc, void *cbdata);

18.2.261.1.1. Python Syntax

from pmix import *

foo = PMIxServer()
# ... after a successful foo.init() ...
source = {'nspace': "myapp", 'rank': 0}
channel = PMIX_FWD_STDOUT_CHANNEL
data = {'bytes': "hello world"}
pydirs = []
rc = foo.iof_deliver(source, channel, data, pydirs)

18.2.261.2. INPUT PARAMETERS

source: Pointer to a pmix_proc_t(5) identifying the process that generated the data being forwarded.
channel: The pmix_iof_channel_t(5) identifying the I/O channel of the data — e.g., PMIX_FWD_STDOUT_CHANNEL or PMIX_FWD_STDERR_CHANNEL.
bo: Pointer to a pmix_byte_object_t(5) containing the payload to be delivered.
info: Array of pmix_info_t(5) structures conveying optional metadata describing the data (see DIRECTIVES). A NULL value (with ninfo of zero) is supported when no metadata is provided.
ninfo: Number of elements in the info array.
cbfunc: Callback function of type pmix_op_cbfunc_t invoked once the library no longer requires access to the provided data. A NULL value makes the call blocking (see DESCRIPTION).
cbdata: Opaque pointer that is passed, unmodified, to cbfunc.

18.2.261.3. DESCRIPTION

Pass forwarded I/O — such as the stdout or stderr output of a remote process — into the local PMIx server library for distribution to its clients. The library is responsible for determining which of its clients have registered (via PMIx_IOF_pull(3)) to receive data from the given source on the given channel, and for delivering the payload only to those clients.

PMIx_server_IOF_deliver supports both blocking and non-blocking operation. When cbfunc is non-NULL the call is non-blocking: it thread-shifts the request into the library’s progress thread, returns immediately, and invokes cbfunc once the library no longer needs the provided byte object. When cbfunc is NULL the call is blocking: it does not return until the operation has completed.

The host RM is required to retain the bo byte object (and the info array) until the callback is executed — or, in the blocking case, until the function returns. If the function returns a non-success status, the library did not take ownership and the host may release the data immediately.

18.2.261.4. DIRECTIVES

The following attributes may appear in the info array to describe the forwarded data. Unrecognized attributes are ignored.

PMIX_IOF_COMPLETE (bool) — indicates that the specified source I/O channel has been closed; no further data will be forwarded from it.
PMIX_IOF_TAG_OUTPUT (bool) — the output should be tagged with the identity (namespace/rank) and channel of its source.
PMIX_IOF_RANK_OUTPUT (bool) — the output should be tagged with the rank from which it originated.
PMIX_IOF_XML_OUTPUT (bool) — the output should be formatted in XML.
PMIX_IOF_OUTPUT_RAW (bool) — deliver the output without buffering it into complete lines.

18.2.261.5. CALLBACK FUNCTION

For the non-blocking form, the cbfunc has the signature pmix_op_cbfunc_t:

typedef void (*pmix_op_cbfunc_t)(pmix_status_t status, void *cbdata);

The library invokes cbfunc with the final status and the original cbdata once it no longer requires access to the bo byte object and the info array, allowing the host to release them.

18.2.261.6. RETURN VALUE

For the non-blocking form (cbfunc is non-NULL), a return of PMIX_SUCCESS indicates only that the request was accepted for processing; the final status is delivered through cbfunc. For the blocking form (cbfunc is NULL), a return of PMIX_OPERATION_SUCCEEDED indicates that the request was immediately processed and completed successfully — cbfunc is not called. Possible return values include:

PMIX_SUCCESS — (non-blocking form) the request was accepted for processing.
PMIX_OPERATION_SUCCEEDED — (blocking form) the operation completed successfully.
PMIX_ERR_NOMEM — the library was unable to allocate memory for the request.
PMIX_ERR_NOT_AVAILABLE — the operation cannot be serviced because the library’s progress engine has been stopped.
PMIX_ERR_INIT — the PMIx server library has not been initialized.

Any other negative value indicates an appropriate error condition. PMIx error constants are defined in pmix_common.h.

18.2.261.7. NOTES

This function is the server-side counterpart to the client I/O-forwarding registration API PMIx_IOF_pull(3): the host RM collects output from remote processes and injects it here, and the library routes it to whichever local clients requested it.