19.2.256. PMIx_Register_attributes

PMIx_Register_attributes — Register the attributes the host environment supports for a given server-module function.

19.2.256.1. SYNOPSIS

#include <pmix_server.h>

pmix_status_t PMIx_Register_attributes(char *function, char *attrs[]);

19.2.256.1.1. Python Syntax

from pmix import *

foo = PMIxServer()
# ... after a successful foo.init() ...
# attrs is a list of attribute-name strings supported for the function
attrs = ["PMIX_TIMEOUT", "PMIX_WAIT"]
rc = foo.register_attributes("allocate", attrs)

19.2.256.2. INPUT PARAMETERS

function: The string name of the pmix_server_module_t(5) function whose supported attributes are being registered — for example, "register_events", "validate_credential", or "allocate".
attrs: A NULL-terminated argv-style array of attribute-name strings supported by the host environment for the specified function.

19.2.256.3. DESCRIPTION

Register with the local PMIx server library the attributes that the host environment supports for a specific pmix_server_module_t function. Host environments use this API so that, when a client or tool later queries the library (via PMIx_Query_info(3) with the PMIX_QUERY_ATTRIBUTE_SUPPORT key) for the attributes supported by a user-facing API, the library can accurately report which attributes the host will honor.

Attributes registered through this API are recorded at the host level (PMIX_HOST_ATTRIBUTES); the PMIx library separately and automatically registers the attributes it supports internally at the client, server, and tool levels during initialization. It is the library’s responsibility to associate the host-registered attributes for a server-module function with their corresponding user-facing API and level when answering a query.

This is a blocking operation: internally the request is thread-shifted onto the progress thread, and the call does not return until the registration has been recorded. The function name and attrs array are copied by the library, so the caller need not keep them valid after the call returns.

Host environments are strongly encouraged to register all supported attributes immediately after initializing the library (see PMIx_server_init(3)), before servicing any user requests, so that attribute-support queries are correctly answered from the outset.

19.2.256.4. RETURN VALUE

Returns PMIX_SUCCESS when the attributes are successfully registered. Otherwise a negative PMIx error constant is returned, including:

PMIX_ERR_REPEAT_ATTR_REGISTRATION — the attributes for this function have already been registered at the host level. Duplicate registration at the same level for a function is not permitted; registrations at different levels are tracked independently.
PMIX_ERR_INIT — the PMIx server library has not been initialized.
PMIX_ERR_NOT_AVAILABLE — the operation cannot be serviced because the library’s progress engine has been stopped.
PMIX_ERR_BAD_PARAM — an invalid registration level was specified internally.

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

19.2.256.5. NOTES

This is a server-role API, available only after PMIx_server_init(3).

The signature shown above is that of the OpenPMIx library. The PMIx Standard describes an alternative signature for this function that takes an array of pmix_regattr_t structures together with a count; the implementation in this release accepts the simpler NULL-terminated string array shown here.

19.2.256.6. PROGRESS THREAD RESTRICTION

A blocking PMIx call must not be made from within the PMIx progress thread. Any code the library itself invokes runs on that thread: an event handler registered through PMIx_Register_event_handler(3), a callback passed to a non-blocking PMIx API, and — in a server or tool — the completion of a host-module up-call. A blocking call waits for work that the progress thread has to perform, so making one from that thread waits for itself and never returns. The PMIx Standard disallows it, and there is no way for an implementation to service such a request.

Where this call has a blocking form — including the blocking behavior a non-blocking entry point adopts when it is passed a NULL cbfunc — that form detects the situation and returns PMIX_ERR_WOULD_BLOCK immediately, accompanied by a diagnostic naming the call. Nothing is done and no callback is invoked.

PMIX_ERR_WOULD_BLOCK here is not a transient condition to retry: it reports a call that cannot be serviced from where it was made. Reissue it as the non-blocking form with a callback, or from a thread of your own.