18.2.278. PMIx_IOF_push

PMIx_IOF_push — Push data collected locally (typically from standard input) to the standard input of target recipients.

18.2.278.1. SYNOPSIS

#include <pmix_tool.h>

pmix_status_t PMIx_IOF_push(const pmix_proc_t targets[], size_t ntargets,
                            pmix_byte_object_t *bo,
                            const pmix_info_t directives[], size_t ndirs,
                            pmix_op_cbfunc_t cbfunc, void *cbdata);

18.2.278.1.1. Python Syntax

from pmix import *

foo = PMIxTool()
# ... after a successful foo.init() and attachment to a server ...
pytargets = [{'nspace': "target-nspace", 'rank': PMIX_RANK_WILDCARD}]
# data carries the bytes to be delivered to the targets' stdin
data = {'bytes': "some input text"}
pydirs = []
rc = foo.iof_push(pytargets, data, pydirs)

18.2.278.2. INPUT PARAMETERS

targets: Pointer to an array of pmix_proc_t(5) identifiers naming the processes to which the data is to be delivered. A rank of PMIX_RANK_WILDCARD directs that all processes in the given namespace receive a copy of the data.
ntargets: Number of elements in the targets array.
bo: Pointer to a pmix_byte_object_t(5) containing the payload (typically stdin data) to be delivered. May be NULL when the call is being used solely to start or stop automatic stdin collection via directives.
directives: Pointer to an array of pmix_info_t(5) structures conveying directives that control the behavior of the request (see DIRECTIVES). A NULL value is supported when no directives are desired.
ndirs: Number of elements in the directives array.
cbfunc: Callback function of type pmix_op_cbfunc_t invoked when the operation has completed. A NULL value makes the call blocking (see DESCRIPTION).
cbdata: Opaque pointer passed, unmodified, to cbfunc.

18.2.278.3. DESCRIPTION

PMIx_IOF_push is used in one of three ways:

to push data the caller has collected itself (typically from stdin or a file) to the standard input of the target recipients;
to request that the PMIx library automatically collect the caller’s own stdin and forward it to the target recipients (via the PMIX_IOF_PUSH_STDIN directive); or
to indicate that automatic collection and transmittal of stdin is to stop (via the PMIX_IOF_COMPLETE directive).

The request is thread-shifted onto the PMIx progress thread for processing. When cbfunc is non-NULL the call is non-blocking: it returns PMIX_SUCCESS immediately and the result is delivered later through cbfunc. When cbfunc is NULL the call is blocking and the result of the operation is carried in the return value.

Execution of cbfunc serves as notice that the PMIx library no longer requires the caller to maintain the bo data object; it does not indicate that the payload has been delivered to the targets. As with all non-blocking PMIx APIs, callers must keep the targets, bo, and directives arguments valid until the callback has fired.

18.2.278.4. DIRECTIVES

The following attributes are required to be supported by PMIx libraries that provide I/O forwarding:

PMIX_IOF_CACHE_SIZE (uint32_t) — requested size, in bytes, of the server cache for each specified channel.
PMIX_IOF_DROP_OLDEST (bool) — in an overflow situation, drop the oldest cached bytes to make room for newly arriving data.
PMIX_IOF_DROP_NEWEST (bool) — in an overflow situation, drop newly arriving bytes until room becomes available in the cache.

The following attributes are optional:

PMIX_IOF_BUFFERING_SIZE (uint32_t) — control the grouping of data so that it is delivered in blocks of the requested size.
PMIX_IOF_BUFFERING_TIME (uint32_t) — maximum time, in seconds, to buffer data before delivering it.
PMIX_IOF_PUSH_STDIN (bool) — request that the PMIx library collect the stdin of the caller and forward it to the specified targets. All collected data is sent to the same targets until stdin is closed or a subsequent PMIx_IOF_push call carrying PMIX_IOF_COMPLETE terminates the forwarding.
PMIX_IOF_COMPLETE (bool) — indicate that forwarding of stdin to the targets is to be terminated.

18.2.278.5. CALLBACK FUNCTION

When provided, cbfunc has the signature pmix_op_cbfunc_t:

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

It is invoked with the final status of the operation and the cbdata pointer that was supplied to PMIx_IOF_push.

18.2.278.6. RETURN VALUE

For the non-blocking form (cbfunc non-NULL), a return of PMIX_SUCCESS indicates only that the request was accepted for processing; the final status is delivered to cbfunc.

For the blocking form (cbfunc is NULL), the return value carries the result of the operation — PMIX_SUCCESS (or PMIX_OPERATION_SUCCEEDED when the request was satisfied immediately) on success, or a negative error constant on failure. Error constants that may be returned include:

PMIX_ERR_INIT — the PMIx library has not been initialized.
PMIX_ERR_NOT_AVAILABLE — the operation cannot be serviced because the library’s progress engine has been stopped.

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

18.2.278.7. NOTES

Use of PMIX_RANK_WILDCARD to target all processes in a namespace is supported but should be used with care due to the bandwidth and memory footprint it can incur.