20.2.107. PMIx_Info_list_convert

PMIx_Info_list_convert — Convert an opaque pmix_info_t(5) list into a contiguous pmix_data_array_t(5)

20.2.107.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Info_list_convert(void *ptr, pmix_data_array_t *par);

20.2.107.1.1. Python Syntax

No Python equivalent

20.2.107.2. INPUT/OUTPUT PARAMETERS

ptr: (IN) Opaque list handle returned by PMIx_Info_list_start(3).
par: (OUT) Pointer to a caller-instantiated pmix_data_array_t that will receive the resulting array of pmix_info_t structures.

20.2.107.3. DESCRIPTION

Transfer the accumulated contents of the list identified by ptr into the pmix_data_array_t referenced by par. The function initializes par for type PMIX_INFO, allocates an array of pmix_info_t structures sized to the number of list entries, sets par->type and par->size accordingly, and deep-copies each list entry into successive elements of the array in list order.

The resulting array is fully independent of the list: the list may subsequently be released (via PMIx_Info_list_release(3)) without affecting the converted array. This is the normal terminal step of the list-building workflow — build the list, convert it to an array suitable for passing to a PMIx API, then release the list.

The storage referenced by par->array is allocated by the library and becomes the caller’s responsibility; it should ultimately be freed with the appropriate PMIx data-array release facilities (for example PMIX_DATA_ARRAY_DESTRUCT).

20.2.107.4. RETURN VALUE

Returns one of:

PMIX_SUCCESS — the list was converted successfully.
PMIX_ERR_BAD_PARAM — ptr or par was NULL.
PMIX_ERR_EMPTY — the list contained no entries; no array is allocated.
PMIX_ERR_NOMEM — the destination array could not be allocated.
any other PMIx error constant — the first failure recorded on the list by an earlier operation, reported here even though that operation has already returned it once.

20.2.107.5. NOTES

An empty list is reported as PMIX_ERR_EMPTY rather than producing a zero-length array, so callers that may legitimately build an empty list should handle that return value.

An earlier failure is reported ahead of PMIX_ERR_EMPTY: a list left empty because its only add failed is a failure, not an empty list. This makes the conversion the single place a caller assembling a long list has to test. A converted array is complete only when this returns PMIX_SUCCESS.

20.2.107.6. EXAMPLES

void *ilist;
pmix_data_array_t darray;
pmix_status_t rc;

ilist = PMIx_Info_list_start();
PMIx_Info_list_add(ilist, PMIX_HOSTNAME, host, PMIX_STRING);

rc = PMIx_Info_list_convert(ilist, &darray);
if (PMIX_SUCCESS == rc) {
    /* darray.array now holds darray.size pmix_info_t entries */
}

PMIx_Info_list_release(ilist);