18.2.112. PMIx_Info_list_start

PMIx_Info_list_start — Initialize an opaque list for accumulating pmix_info_t(5) structures

18.2.112.1. SYNOPSIS

#include <pmix.h>

void* PMIx_Info_list_start(void);

18.2.112.1.1. Python Syntax

No Python equivalent

18.2.112.2. INPUT PARAMETERS

None

18.2.112.3. DESCRIPTION

Constructing an array of pmix_info_t structures for passing to a PMIx API can be tedious, since the pmix_info_t is not itself a list object and the number of entries is frequently not known in advance. The PMIx_Info_list_start function begins that process by allocating an opaque, implementation-dependent list object and returning a void* handle to it.

The returned handle is passed to the other PMIx_Info_list_* routines to accumulate entries — for example PMIx_Info_list_add(3), PMIx_Info_list_xfer(3), or PMIx_Info_list_prepend(3) — and is ultimately converted into a contiguous pmix_data_array_t(5) of pmix_info_t via PMIx_Info_list_convert(3). When the caller is finished with the list, the handle must be passed to PMIx_Info_list_release(3) to free all associated storage.

The object referenced by the returned handle is opaque: the caller must not modify or dereference it.

18.2.112.4. RETURN VALUE

Returns a void* handle to the newly created list, or NULL if the object could not be allocated.

18.2.112.5. NOTES

PMIx_Info_list_start begins a workflow that is completed by PMIx_Info_list_release(3). Every handle obtained from PMIx_Info_list_start must eventually be released to avoid leaking memory.

18.2.112.6. EXAMPLES

Build a list, convert it, and release it:

void *ilist;
pmix_data_array_t darray;
pmix_status_t rc;

ilist = PMIx_Info_list_start();

PMIx_Info_list_add(ilist, PMIX_RANK, &rank, PMIX_PROC_RANK);
PMIx_Info_list_add(ilist, PMIX_HOSTNAME, host, PMIX_STRING);

rc = PMIx_Info_list_convert(ilist, &darray);

PMIx_Info_list_release(ilist);