18.2.262. PMIx_server_generate_cpuset

PMIx_server_generate_cpuset — Generate a cpuset from a PMIx string representation.

18.2.262.1. SYNOPSIS

#include <pmix_server.h>

pmix_status_t PMIx_server_generate_cpuset(const char *cpuset_string,
                                          pmix_cpuset_t *cpuset);

18.2.262.1.1. Python Syntax

No Python equivalent

18.2.262.2. INPUT PARAMETERS

cpuset_string: NULL-terminated PMIx string representation of a cpuset, as produced by PMIx_server_generate_cpuset_string(3). The string must begin with a colon-delimited source prefix (e.g., "hwloc:0-3") identifying the subsystem able to decode the remainder.

18.2.262.3. OUTPUT PARAMETERS

cpuset: Pointer to caller-provided storage for a pmix_cpuset_t(5) structure. On success, the source and bitmap fields are populated with a decoded copy of the bitmap. The caller must provide the storage for the structure itself; the library allocates the internal source string and bitmap object, which the caller is responsible for releasing (for example, via PMIx_Cpuset_destruct).

18.2.262.4. DESCRIPTION

Provide a function by which the host environment can convert a PMIx string representation of a cpuset into the corresponding cpuset bitmap. This is the reciprocal of PMIx_server_generate_cpuset_string(3): the source prefix embedded in the string is used to route the request to the subsystem (e.g., hwloc) that can decode it, and the decoded bitmap is returned in the caller-supplied structure.

The operation is performed synchronously in the caller’s thread; it does not thread-shift into the PMIx progress engine and does not invoke a callback.

This API is a PMIx library convenience routine; it is not part of the PMIx Standard.

18.2.262.5. RETURN VALUE

Returns one of the following:

PMIX_SUCCESS — the string was parsed and the bitmap returned in cpuset.
PMIX_ERR_INIT — the PMIx server library has not been initialized.
PMIX_ERR_BAD_PARAM — the string was malformed — for example, it lacked a colon-delimited source prefix or the encoded bitmap could not be decoded.
another non-success PMIx error constant — no configured provider recognized the source prefix of the supplied string, so no cpuset could be generated.

PMIx error constants are defined in pmix_common.h.

18.2.262.6. NOTES

This API is restricted to the server role and must be called only after a successful PMIx_server_init(3). The caller owns the contents populated into the cpuset structure and must release them when no longer needed.