18.2.263. PMIx_server_generate_cpuset_string

PMIx_server_generate_cpuset_string — Generate a PMIx string representation of a provided cpuset.

18.2.263.1. SYNOPSIS

#include <pmix_server.h>

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

18.2.263.1.1. Python Syntax

from pmix import *

foo = PMIxServer()
# ... after a successful foo.init() ...
# cpuset is a Python dict describing the bitmap (e.g. as
# returned by foo.get_cpuset())
rc, cpuset_string = foo.generate_cpuset_string(cpuset)

18.2.263.2. INPUT PARAMETERS

cpuset: Pointer to a pmix_cpuset_t(5) structure containing the bitmap of assigned processing units (PUs). The source field identifies the subsystem (e.g., "hwloc") that produced the bitmap, and the bitmap field points to the corresponding implementation-specific object.

18.2.263.3. OUTPUT PARAMETERS

cpuset_string: Address where a pointer to a freshly allocated, NULL-terminated string representation of the input bitmap is returned. The caller is responsible for releasing the string with free().

18.2.263.4. DESCRIPTION

Provide a function by which the host environment can generate a string representation of a cpuset bitmap for inclusion in the call to PMIx_server_register_nspace(3). This function shall only be called for local client processes, with the returned string included in the job-level information (via the PMIX_CPUSET attribute) provided to local clients. Local clients can use these strings to obtain their PU bindings via the PMIx_Parse_cpuset_string API.

The returned string is prefixed by the source field of the provided cpuset followed by a colon (e.g., "hwloc:0-3"); the remainder of the string represents the PUs to which the process is bound as expressed by the underlying implementation. This prefix allows the reciprocal operation, PMIx_server_generate_cpuset(3), to route the string back to the subsystem that can decode it.

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.

18.2.263.5. RETURN VALUE

Returns one of the following:

PMIX_SUCCESS — the string was generated and returned in cpuset_string.
PMIX_ERR_INIT — the PMIx server library has not been initialized.
PMIX_ERR_BAD_PARAM — cpuset was NULL or its bitmap field was NULL. In this case cpuset_string is set to NULL.
another non-success PMIx error constant — no configured provider recognized the source of the supplied cpuset, so no string could be generated.

PMIx error constants are defined in pmix_common.h.

18.2.263.6. NOTES

This API is restricted to the server role and must be called only after a successful PMIx_server_init(3). The returned string is owned by the caller.