19.2.39. PMIx_Load_topology

PMIx_Load_topology — Load the local hardware topology description.

19.2.39.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Load_topology(pmix_topology_t *topo);

19.2.39.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after a successful foo.init() ...
rc = foo.load_topology()

19.2.39.2. INPUT PARAMETERS

topo: Pointer to a pmix_topology_t structure into which the topology description of the local node is to be loaded. The structure must be initialized by the caller prior to the call (for example, with PMIx_Topology_construct()). If a particular topology source is required (e.g., "hwloc"), the source field of the structure must be set to that value before the call; otherwise the library selects an available source.

19.2.39.3. DESCRIPTION

Obtain the topology description of the local node and load it into the provided pmix_topology_t structure. This is a blocking operation that returns once the topology has been loaded.

If the source field of the provided pmix_topology_t is set, the PMIx library must return a description from the specified implementation or else indicate that the implementation is not available by returning PMIX_ERR_NOT_SUPPORTED.

The returned description should be treated as a read-only object; attempts to modify it may result in errors. The PMIx library is responsible for performing any required cleanup of the returned topology when the client library finalizes.

Ownership of the source field depends on who set it:

If the caller set the source field before the call to request a particular implementation, that string belongs to the caller, and the caller remains responsible for releasing it.
If the caller did not set the source field, the library fills it in on return with a read-only, statically allocated string identifying the source of the returned topology. The caller must not modify or release this string; the library manages its lifetime.

In neither case should the caller destruct or free the returned topology itself (for example with PMIx_Topology_destruct()): the topology object is shared, library-managed state, and releasing it would corrupt the library’s internal copy. The library performs the necessary cleanup at finalize.

19.2.39.4. RETURN VALUE

Returns PMIX_SUCCESS when a valid topology description has been loaded. On error, a negative value corresponding to a PMIx error constant is returned, including:

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.
PMIX_ERR_NOT_FOUND — the requested topology could not be found.
PMIX_ERR_NOT_SUPPORTED — the requested source is not available in the current implementation.

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

19.2.39.5. NOTES

It is the responsibility of the caller to ensure that the topo argument is properly initialized prior to calling this API. If no source was specified, the caller should inspect the returned source field to verify that the returned topology description is compatible with the caller’s code.

19.2.39.6. 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.