Scroll to navigation

PMIX_SERVER_GENERATE_CPUSET_STRING(3) OpenPMIx PMIX_SERVER_GENERATE_CPUSET_STRING(3)

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

SYNOPSIS

#include <pmix_server.h>
pmix_status_t PMIx_server_generate_cpuset_string(const pmix_cpuset_t *cpuset,


                                                 char **cpuset_string);


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)


INPUT PARAMETERS

•
cpuset: Pointer to a pmix_cpuset_t(5) <#man5-pmix-cpuset-t> 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.

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().

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) <#man3-pmix-server-register-nspace>. 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) <#man3-pmix-server-generate-cpuset>, 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.

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.

NOTES

This API is restricted to the server role and must be called only after a successful PMIx_server_init(3) <#man3-pmix-server-init>. The returned string is owned by the caller.

See also:

PMIx_server_init(3) <#man3-pmix-server-init>, PMIx_server_register_nspace(3) <#man3-pmix-server-register-nspace>, PMIx_server_generate_cpuset(3) <#man3-pmix-server-generate-cpuset>, PMIx_server_generate_locality_string(3) <#man3-pmix-server-generate-locality-string>, pmix_cpuset_t(5) <#man5-pmix-cpuset-t>, pmix_status_t(5) <#man5-pmix-status-t>


Copyright

2014-2026, OpenPMIx Community

September 27, 2026