18.2.110. PMIx_Info_list_insert

PMIx_Info_list_insert — Append an existing pmix_info_t(5) to an opaque list by reference, without copying its payload

18.2.110.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Info_list_insert(void *ptr, pmix_info_t *info);

18.2.110.1.1. Python Syntax

No Python equivalent

18.2.110.2. INPUT PARAMETERS

ptr: Opaque list handle returned by PMIx_Info_list_start(3).
info: Pointer to an existing pmix_info_t whose contents are to be placed on the list.

18.2.110.3. DESCRIPTION

Append the provided pmix_info_t to the end of the list identified by ptr without deep-copying its payload. The structure is copied shallowly (via memcpy), so any pointers held in info — the key string, value data, embedded arrays — are preserved and the list entry references the same underlying memory as the caller’s info.

To prevent a later double-free, the new list entry is marked persistent (PMIX_INFO_SET_PERSISTENT), meaning its payload will not be released when the list is released or destructed. Ownership of the referenced memory therefore remains with the caller.

This differs sharply from PMIx_Info_list_xfer(3), which performs a deep copy and takes ownership of the copied data. Use PMIx_Info_list_insert only when the caller intends to keep the source info (and its backing memory) alive for as long as the list is in use.

18.2.110.4. RETURN VALUE

Returns PMIX_SUCCESS on success, or a negative PMIx error constant such as PMIX_ERR_NOMEM if the list entry could not be allocated.

18.2.110.5. NOTES

Because the entry is stored by reference and marked persistent, the caller must ensure the memory referenced by info remains valid for the lifetime of the list, and is responsible for freeing that memory itself. Converting the list via PMIx_Info_list_convert(3) produces an independent deep copy in the resulting array.