19.2.260. PMIx_server_collect_job_info

PMIx_server_collect_job_info — Collect the job-level information for an array of processes into a data buffer.

19.2.260.1. SYNOPSIS

#include <pmix_server.h>

pmix_status_t PMIx_server_collect_job_info(pmix_proc_t *procs, size_t nprocs,
                                           pmix_data_buffer_t *dbuf);

19.2.260.1.1. Python Syntax

from pmix import *

foo = PMIxServer()
# ... after a successful foo.init() and register_nspace() ...
# the procs are a list of Python proc dictionaries - only their
# namespaces matter, and the list cannot be empty
rc, blob = foo.collect_job_info([{'nspace': "myjob", 'rank': 0}])
# blob is a byte object, {'bytes': bytes, 'size': int}

19.2.260.2. INPUT PARAMETERS

procs: Array of pmix_proc_t(5) structures identifying the processes whose job-level information is to be collected. The library reduces the array to its set of unique namespaces and collects the job-level data for each.
nprocs: Number of elements in the procs array.

19.2.260.3. OUTPUT PARAMETERS

dbuf: Pointer to a pmix_data_buffer_t(5) provided by the caller. On success, the buffer is loaded with the packed job-level information — for each participating namespace, the namespace name followed by its job-level key-value data, wrapped as a byte object. The caller owns the resulting buffer contents and must release them with PMIx_Data_buffer_destruct (or PMIx_Data_buffer_release) when no longer needed.

19.2.260.4. DESCRIPTION

Collect the job-level information already held by the local PMIx server library for the namespaces represented in the procs array, packing it into the caller-provided data buffer for transmission or later replay. This is used, for example, to bootstrap a peer server with the job-level data it needs for a set of processes without requiring a separate registration for each namespace.

For each unique namespace in procs, the library locates the namespace in its internal tables and fetches its job-level data — preferring a local client’s data store when one exists, otherwise falling back to the server’s own storage. Namespaces the server does not know are silently skipped. The packed result for each namespace is appended to dbuf as a byte object.

Unlike most server APIs, PMIx_server_collect_job_info is a blocking operation and does not take a callback: internally it thread-shifts the request into the library’s progress thread, waits for completion, and returns the final status directly. The output buffer is populated only on a PMIX_SUCCESS return.

19.2.260.5. RETURN VALUE

Returns one of the following:

PMIX_SUCCESS — the job-level information was collected and loaded into dbuf.
PMIX_ERR_NOT_FOUND — the requested job-level information could not be located for the specified namespace(s).
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.

On any non-success return, the contents of dbuf are unspecified and must not be used. Any other negative value indicates an appropriate error condition. PMIx error constants are defined in pmix_common.h.

19.2.260.6. NOTES

This is an OpenPMIx server-library extension; it is not part of the PMIx Standard. It is available only after the server library has been initialized with PMIx_server_init(3).

19.2.260.7. PROGRESS THREAD RESTRICTION

A blocking PMIx call must not be made from within the PMIx progress thread. Any code the library itself invokes runs on that thread: an event handler registered through PMIx_Register_event_handler(3), a callback passed to a non-blocking PMIx API, and — in a server or tool — the completion of a host-module up-call. A blocking call waits for work that the progress thread has to perform, so making one from that thread waits for itself and never returns. The PMIx Standard disallows it, and there is no way for an implementation to service such a request.

Where this call has a blocking form — including the blocking behavior a non-blocking entry point adopts when it is passed a NULL cbfunc — that form detects the situation and returns PMIX_ERR_WOULD_BLOCK immediately, accompanied by a diagnostic naming the call. Nothing is done and no callback is invoked.

PMIX_ERR_WOULD_BLOCK here is not a transient condition to retry: it reports a call that cannot be serviced from where it was made. Reissue it as the non-blocking form with a callback, or from a thread of your own.