18.2.255. PMIx_server_deregister_resources

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

18.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);

18.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': {'value': "cluster-a", 'val_type': PMIX_STRING}}]
rc = foo.deregister_resources(directives)

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

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

18.2.255.4. DIRECTIVES

The key of each info element selects the entry to remove. Qualifiers may be included to scope the removal, for example:

PMIX_NODE_INFO_ARRAY (pmix_data_array_t*) — scope the removal to a specific node, identified within the array by PMIX_NODEID or PMIX_HOSTNAME.
PMIX_FABRIC_DEVICE_NAME (char*) — the name of a fabric device to remove.
PMIX_DEVICE_ID (char*) — a system-unique device identifier; sufficient on its own to remove the corresponding device.

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

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

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