19.2.255. PMIx_server_deregister_resources

PMIx_server_deregister_resources — Remove non-namespace-related information from the local PMIx server library.

19.2.255.1. SYNOPSIS

#include <pmix_server.h>

pmix_status_t PMIx_server_deregister_resources(pmix_info_t info[], size_t ninfo,
                                               pmix_op_cbfunc_t cbfunc,
                                               void *cbdata);

19.2.255.1.1. Python Syntax

from pmix import *

foo = PMIxServer()
# ... after a successful foo.init() ...
# only the keys of the directives are significant here
directives = [{'key': PMIX_CLUSTER_ID,
               'value': "cluster-a", 'val_type': PMIX_STRING}]
rc = foo.deregister_resources(directives)

19.2.255.2. INPUT PARAMETERS

info: Array of pmix_info_t(5) structures identifying the information to be removed. Only the key field of each element is used to select what to remove; the associated values are ignored except where they serve as qualifiers (see DIRECTIVES).
ninfo: Number of elements in the info array.
cbfunc: Callback function of type pmix_op_cbfunc_t invoked when the operation completes. A NULL value makes the call blocking (see DESCRIPTION).
cbdata: Opaque pointer passed, unmodified, to cbfunc.

19.2.255.3. DESCRIPTION

Remove information about resources not associated with a given namespace — previously registered with PMIx_server_register_resources(3) — from the local PMIx server library. Only the key fields of the provided info array are used to identify the entries to remove; the associated values are ignored except where they serve as qualifiers to the request. Each matching entry is located in the server’s global data cache and deleted.

For example, to remove a specific fabric device from a given node, the info array might include a PMIX_NODE_INFO_ARRAY containing the PMIX_NODEID or PMIX_HOSTNAME that identifies the node hosting the device, together with a PMIX_FABRIC_DEVICE_NAME specifying the device. Alternatively, the device may be removed using only its PMIX_DEVICE_ID, which is unique across the entire system.

PMIx_server_deregister_resources supports both calling conventions. When cbfunc is non-NULL the function is non-blocking: the request is thread-shifted onto the progress thread, the function returns PMIX_SUCCESS, and cbfunc is invoked with the completion status. When cbfunc is NULL the function is blocking: it does not return until the operation completes, returning PMIX_OPERATION_SUCCEEDED on success.

As with all non-blocking PMIx APIs, when a callback is supplied the caller must keep the info array valid until cbfunc is invoked.

19.2.255.4. DIRECTIVES

The key of each info element selects the entries to remove. An element whose value is not a data array selects by key alone: every registered entry carrying that key is removed.

An element whose value is a pmix_data_array_t of pmix_info_t narrows the removal. Two kinds of member are recognized within it:

PMIX_NODEID (uint32_t) or PMIX_HOSTNAME (char*) — identifiers. They restrict the removal to the registered entries describing that node. A hostname must match exactly; PMIX_HOSTNAME_ALIASES is not consulted. An array carrying no identifier applies to every entry with that key, which is how a device that is unique across the system is removed without naming its node.
any other member — a target. It selects the elements to remove from within the entries the identifiers chose. A target matches an element directly (same key, same value), or matches an element that contains it: a PMIX_FABRIC_DEVICE element carries its own array of pmix_info_t, so a target naming the device by PMIX_FABRIC_DEVICE_NAME or PMIX_DEVICE_ID removes that whole device from the node.

An array carrying identifiers and no target removes the whole entry for the node it names. If removing the targets leaves an entry describing nothing — only the identifiers remain — the entry itself is removed, since what would be left is what an empty registration would have produced.

For example, to remove one fabric device from a given node, the info array might include a PMIX_NODE_INFO_ARRAY containing the PMIX_NODEID or PMIX_HOSTNAME that identifies the node hosting the device, together with a PMIX_FABRIC_DEVICE_NAME specifying the device.

19.2.255.5. CALLBACK FUNCTION

When cbfunc is provided, it has the signature pmix_op_cbfunc_t:

typedef void (*pmix_op_cbfunc_t)(pmix_status_t status, void *cbdata);

It is invoked with the completion status of the deregistration and the cbdata originally passed to PMIx_server_deregister_resources.

19.2.255.6. RETURN VALUE

For the non-blocking form (cbfunc non-NULL), a return of PMIX_SUCCESS indicates only that the request was accepted for processing; the final status is delivered to cbfunc.

For the blocking form (cbfunc is NULL), a return of PMIX_OPERATION_SUCCEEDED indicates that the operation completed successfully and no callback is invoked. Other returns include:

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.

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

19.2.255.7. NOTES

This is a server-role API, available only after PMIx_server_init(3). Because non-namespace resource information is static, deregistration is not required before finalizing the library — the library cleans up such information as part of its normal finalize operations. Deregistration is needed only when the host environment determines that client processes should no longer have access to the information.

Important

Deregistration takes effect for namespaces registered after the call. Non-namespace resource information is copied into a namespace’s data store when that namespace is registered, so a namespace already registered — and any client already running under it — retains the information. A host that needs the data withheld from a running job cannot achieve that with this call alone.

19.2.255.8. 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.