18.2.123. PMIx_Info_load

PMIx_Info_load — Load a key and typed value into a pmix_info_t(5)

18.2.123.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Info_load(pmix_info_t *info,
                             const char *key,
                             const void *data,
                             pmix_data_type_t type);

18.2.123.1.1. Python Syntax

No Python equivalent

18.2.123.2. INPUT/OUTPUT PARAMETERS

info: Pointer to the pmix_info_t(5) structure to be populated. The function first constructs (initializes) the structure, so any prior contents are overwritten, not released — the caller must ensure the structure holds no live payload that would otherwise leak.

18.2.123.3. INPUT PARAMETERS

key: The string key to store. Must not be NULL.
data: Pointer to the value to load, interpreted according to type. May be NULL for types that carry no data (e.g., PMIX_UNDEF).
type: The pmix_data_type_t(5) describing the datum referenced by data.

18.2.123.4. DESCRIPTION

The PMIx_Info_load function populates a pmix_info_t(5) structure with a key and a typed value. It is equivalent to constructing the structure, copying key into the info’s key field, and then performing a value-load of data (of the given type) into the info’s contained pmix_value_t(5).

The load copies the supplied data: the key string and the value payload are duplicated into memory owned by the info structure, so the caller’s key and data buffers may be freed or reused after the call returns. The memory acquired by the info must subsequently be released with PMIx_Info_destruct(3) (for a caller-owned structure) or PMIx_Info_free(3) (for a library-allocated array).

18.2.123.5. RETURN VALUE

Returns PMIX_SUCCESS on success. On error, one of the negative PMIx error constants is returned, including:

PMIX_ERR_BAD_PARAM: key was NULL.

Other errors (for example PMIX_ERR_NOMEM or an unsupported-type error) may be propagated from the underlying value-load operation.

18.2.123.6. NOTES

PMIx_Info_load is the OpenPMIx routine underlying the historical PMIX_INFO_LOAD macro. That macro is retained in pmix_deprecated.h for backward compatibility and expands to a call to this function, discarding the return status.

18.2.123.7. EXAMPLES

Load a string value under a key:

pmix_info_t info;
pmix_status_t rc;

rc = PMIx_Info_load(&info, "pmix.example.key", "hello", PMIX_STRING);
if (PMIX_SUCCESS != rc) {
    /* handle error */
}
/* ... use info ... */
PMIx_Info_destruct(&info);