18.2.40. PMIx_Parse_cpuset_string

PMIx_Parse_cpuset_string — Parse the processing-unit (PU) binding bitmap from its string representation.

18.2.40.1. SYNOPSIS

#include <pmix.h>

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

18.2.40.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after a successful foo.init() ...
rc, cpuset = foo.parse_cpuset_string("hwloc:0-3")

18.2.40.2. INPUT PARAMETERS

cpuset_string: NULL-terminated string representation of the binding bitmap, as returned by PMIx_Get(3) using the PMIX_CPUSET key. The string is expected to carry a source prefix (e.g., "hwloc:") followed by the source-specific bitmap encoding.

18.2.40.3. OUTPUT PARAMETERS

cpuset: Pointer to a pmix_cpuset_t object where the parsed bitmap is to be stored. On success, the object’s source and bitmap fields are populated; the caller is responsible for releasing the associated storage with PMIx_Cpuset_destruct when done.

18.2.40.4. DESCRIPTION

Parse the string representation of the binding bitmap (as returned by PMIx_Get(3) using the PMIX_CPUSET key) and set the corresponding PU binding location information in the provided pmix_cpuset_t object.

The library selects the parser that matches the source prefix of cpuset_string. If the source field of cpuset was pre-set by the caller and does not match the underlying source that provided the binding bitmap, an error is returned.

18.2.40.5. RETURN VALUE

Returns PMIX_SUCCESS on success, with the bitmap loaded into cpuset. 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_BAD_PARAM — the string is malformed — for example, it lacks the source: delimiter, or the source-specific bitmap encoding could not be parsed.

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

18.2.40.6. NOTES

Unlike most PMIx APIs, PMIx_Parse_cpuset_string does not accept an array of pmix_info_t(5) directives. This is an intentional exception: the operation is a purely local parse of a string into a bitmap and takes no attributes.