18.2.36. PMIx_Fabric_update

PMIx_Fabric_update, PMIx_Fabric_update_nb — Update the fabric-related information contained in a registered fabric object.

18.2.36.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Fabric_update(pmix_fabric_t *fabric);

pmix_status_t PMIx_Fabric_update_nb(pmix_fabric_t *fabric,
                                    pmix_op_cbfunc_t cbfunc, void *cbdata);

18.2.36.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after a successful foo.init() and foo.fabric_register() ...
rc, fabricinfo = foo.fabric_update()

18.2.36.2. INPUT PARAMETERS

fabric: Address of the pmix_fabric_t structure that was provided to PMIx_Fabric_register(3). Upon successful completion, the information fields of this structure will have been updated.

The non-blocking form takes two additional parameters:

cbfunc: Callback function of type pmix_op_cbfunc_t to be invoked when the update completes.
cbdata: Opaque pointer that is passed, unmodified, to cbfunc.

18.2.36.3. DESCRIPTION

Update the fabric-related information contained in a previously registered pmix_fabric_t object. This call may be made at any time to request a refresh of the object’s information — for example, to poll for changes to the cost matrix. PMIx_Fabric_update is the blocking form: it does not return until the update is complete (or the operation fails), at which point the information fields of the fabric structure have been updated. PMIx_Fabric_update_nb is the non-blocking form: it returns immediately, and the provided cbfunc is invoked once the update has been applied to the fabric structure.

Because the PMIx library does not provide thread protection for the contents of the pmix_fabric_t structure, the caller is not allowed to access the provided fabric structure while an update is in progress: for the blocking form, until the call returns; for the non-blocking form, until cbfunc has been invoked.

18.2.36.4. RETURN VALUE

For the blocking form, PMIX_SUCCESS indicates that the update completed and the fields of the fabric structure have been refreshed. For the non-blocking form, a return of PMIX_SUCCESS indicates only that the request was accepted for processing; the final status is delivered to cbfunc.

PMIX_SUCCESS — the update completed successfully.
PMIX_OPERATION_SUCCEEDED — (non-blocking form) the request was satisfied immediately and cbfunc will not be called.
PMIX_ERR_NOT_SUPPORTED — the operation cannot be serviced — for example, a server whose host environment does not provide fabric support.
PMIX_ERR_UNREACH — the process is not a server or scheduler and its local PMIx server could not be reached.
PMIX_ERR_NOT_AVAILABLE — the operation cannot be serviced because the library’s progress engine has been stopped.
PMIX_ERR_INIT — the PMIx library has not been initialized.

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

18.2.36.5. NOTES

The fabric object must first have been registered with PMIx_Fabric_register(3). Polling with PMIx_Fabric_update is one of two coordinated methods for refreshing fabric information; the other is to register for PMIX_FABRIC_UPDATE_PENDING and PMIX_FABRIC_UPDATED events. See PMIx_Fabric_register(3) for details.