18.2.41. PMIx_Get_cpuset

PMIx_Get_cpuset — Get the processing-unit (PU) binding bitmap of the current process.

18.2.41.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Get_cpuset(pmix_cpuset_t *cpuset,
                              pmix_bind_envelope_t ref);

18.2.41.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after a successful foo.init() ...
rc, cpuset = foo.get_cpuset(PMIX_CPUBIND_PROCESS)

18.2.41.2. INPUT PARAMETERS

ref: The binding envelope of type pmix_bind_envelope_t to be considered when formulating the bitmap. Valid values are:
- PMIX_CPUBIND_PROCESS (0) — use the location of all threads in the (possibly multi-threaded) process.
- PMIX_CPUBIND_THREAD (1) — use only the location of the thread calling the API.

18.2.41.3. OUTPUT PARAMETERS

cpuset: Pointer to a pmix_cpuset_t object where the 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. If the caller pre-sets the source field, it must match the underlying binding source (e.g., "hwloc").

18.2.41.4. DESCRIPTION

Obtain the PU binding location of the calling process from the local topology and store it in the provided pmix_cpuset_t object based on the specified binding envelope. PMIX_CPUBIND_PROCESS considers all threads of the process, while PMIX_CPUBIND_THREAD considers only the calling thread.

18.2.41.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 — an unrecognized ref binding envelope was supplied.
PMIX_ERR_NOT_FOUND — the binding information could not be obtained from the underlying topology.

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

18.2.41.6. NOTES

A process whose threads are not all bound to the same location may return inconsistent results from calls made by different threads when the PMIX_CPUBIND_THREAD envelope is used.

Unlike most PMIx APIs, PMIx_Get_cpuset does not accept an array of pmix_info_t(5) directives. This is an intentional exception: the operation queries the local topology directly and takes no attributes.