18.2.78. PMIx_Data_unload

PMIx_Data_unload — Unload the contents of a buffer into a byte object for transmission or storage.

18.2.78.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Data_unload(pmix_data_buffer_t *buffer,
                               pmix_byte_object_t *payload);

18.2.78.2. INPUT PARAMETERS

buffer: Pointer to the source pmix_data_buffer_t whose payload is to be unloaded.

18.2.78.3. OUTPUT PARAMETERS

payload: Pointer to a pmix_byte_object_t(5) into which the buffer’s payload is placed. The structure is initialized by the function before use; on return its bytes and size fields describe the extracted data.

18.2.78.4. DESCRIPTION

Extract the not-yet-unpacked portion of buffer’s payload into the payload byte object, giving the caller direct access to the packed data — for example, to hand it to a transmission or storage routine. This is the inverse of PMIx_Data_load(3).

Only the region of the payload that has not already been consumed by a prior PMIx_Data_unpack(3) is unloaded; any portion that was previously unpacked is not included. If nothing has yet been unpacked from the buffer, the entire payload region is handed back directly without a byte-copy (an ownership transfer); otherwise the remaining region is copied into freshly allocated memory. In either case the payload byte object owns the returned bytes on completion, and the caller is responsible for releasing that memory (e.g., with PMIX_BYTE_OBJECT_DESTRUCT or by calling free on payload->bytes).

This is a destructive operation on the buffer. While the data returned in payload is undisturbed, the function clears the buffer’s pointers to that data by destructing and re-constructing it, leaving the buffer empty. The buffer and the payload are thereby completely separated, and the caller is free to release the buffer without affecting the unloaded data.

If the buffer contains no payload, the function succeeds and returns an empty byte object.

18.2.78.5. RETURN VALUE

Returns PMIX_SUCCESS on success. On error, a negative value corresponding to a PMIx error constant is returned, including:

PMIX_ERR_BAD_PARAM — the buffer and/or payload pointer is NULL.
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.

18.2.78.6. NOTES

The unloaded payload is in packed (wire) form. It may be reloaded into a buffer for later unpacking with PMIx_Data_load(3).