19.2.20. PMIx_Resource_block

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

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

19.2.20.1.1. Python Syntax

from pmix import *

foo = PMIxClient()
# ... after a successful foo.init() ...
# the resource units are a list of Python dictionaries, each naming a
# device type and a count; the directives are a list of Python
# ``pmix_info_t`` dictionaries
units = [{'type': PMIX_DEVTYPE_GPU, 'count': 4}]
rc = foo.resource_block(PMIX_RESOURCE_BLOCK_DEFINE, "myblock", units, [])

# the non-blocking form returns as soon as the request has been accepted
# and reports the result by executing a callback on the PMIx progress
# thread. The callback is run if and only if the call returned
# PMIX_SUCCESS, and must not itself make a blocking PMIx call.
def donecb(status, cbdata):
    print("resource block completed:", foo.error_string(status))
rc = foo.resource_block_nb(PMIX_RESOURCE_BLOCK_DEFINE, "myblock",
                           units, [], donecb, "mycbdata")

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

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

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

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

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

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