18.2.20. PMIx_Resource_block

PMIx_Resource_block, PMIx_Resource_block_nb — Define or modify a named resource block for use in allocation operations.

18.2.20.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Resource_block(pmix_resource_block_directive_t directive,
                                  char *block,
                                  const pmix_resource_unit_t *res, size_t nres,
                                  const pmix_info_t *info, size_t ninfo);

pmix_status_t PMIx_Resource_block_nb(pmix_resource_block_directive_t directive,
                                     char *block,
                                     const pmix_resource_unit_t *res, size_t nres,
                                     const pmix_info_t *info, size_t ninfo,
                                     pmix_op_cbfunc_t cbfunc, void *cbdata);

18.2.20.2. INPUT PARAMETERS

directive: A directive of type pmix_resource_block_directive_t identifying the requested operation on the block (see DIRECTIVES).
block: NULL-terminated string naming the resource block. The name must be unique within the requestor’s current session.
res: Pointer to an array of pmix_resource_unit_t structures, each of which pairs a device type (type, a pmix_device_type_t) with a count (count), describing the resources to which the operation applies. A NULL value is supported when no resource units are required — for example, when deleting a block.
nres: Number of elements in the res array.
info: Pointer to an array of pmix_info_t(5) structures conveying attributes that qualify the operation. A NULL value is supported when no attributes are desired.
ninfo: Number of elements in the info array.

The non-blocking form adds a callback:

cbfunc: Callback function of type pmix_op_cbfunc_t invoked with the final status once the operation has been processed.
cbdata: Opaque pointer that is passed, unmodified, to cbfunc.

18.2.20.3. DESCRIPTION

Define a named resource “block” that can subsequently be referenced in allocation operations, including the ability to define, extend, reduce, and delete block definitions. A resource block associates a caller-chosen name with a set of resource units (device type and count pairs); the name must be unique within the requestor’s current session.

PMIx_Resource_block is the blocking form: it does not return until the operation is complete, and the return status reflects the outcome. PMIx_Resource_block_nb is the non-blocking form: it returns immediately, and the provided cbfunc is invoked with the final status once the operation has been processed.

As with all non-blocking PMIx APIs, callers of PMIx_Resource_block_nb must keep the block, res, and info arguments valid until cbfunc is invoked.

18.2.20.4. DIRECTIVES

The directive argument is a value of type pmix_resource_block_directive_t that identifies the requested operation:

PMIX_RESOURCE_BLOCK_DEFINE — define a new resource block.
PMIX_RESOURCE_BLOCK_EXTEND — extend an existing block definition by adding the specified resources to the block.
PMIX_RESOURCE_BLOCK_REMOVE — remove the specified resources from the block definition.
PMIX_RESOURCE_BLOCK_DELETE — delete the resource block definition.

Values at or above PMIX_RESOURCE_BLOCK_EXTERNAL are reserved for implementer-defined directives.

The info array may additionally carry the following attribute:

PMIX_RESOURCE_BLOCK_NAME (char*) — name of the resource block that the operation concerns.

18.2.20.5. RETURN VALUE

For the blocking form, PMIX_SUCCESS indicates that the operation completed successfully. 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 operation was successfully processed.
PMIX_ERR_NOT_SUPPORTED — the operation is not supported in the caller’s role or environment — for example, the caller is itself the scheduler, or is a system controller with no scheduler attached.
PMIX_ERR_UNREACH — the caller is not connected to a server capable of servicing the request.
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.20.6. NOTES

This operation is only meaningful when the caller can reach a scheduler, either because the caller’s server is the scheduler or because the caller is a server whose host environment provides a resource-block entry point that can forward the request. A process hosted directly by the scheduler cannot issue a resource-block request against itself and will receive PMIX_ERR_NOT_SUPPORTED.

PMIx_Resource_block is a PMIx library extension and is not part of the published PMIx Standard.