18.2.79. PMIx_Data_load

PMIx_Data_load — Load a data payload into a buffer for subsequent unpacking.

18.2.79.1. SYNOPSIS

#include <pmix.h>

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

18.2.79.2. INPUT PARAMETERS

buffer: Pointer to the destination pmix_data_buffer_t into which the payload is to be loaded. The buffer must have been allocated (e.g., with PMIX_DATA_BUFFER_CREATE) or constructed (e.g., with PMIX_DATA_BUFFER_CONSTRUCT) in advance.
payload: Pointer to a pmix_byte_object_t(5) containing the data payload to be transferred into the buffer.

18.2.79.3. DESCRIPTION

Transfer the contents of the payload byte object into buffer so that the data can subsequently be extracted with PMIx_Data_unpack(3). This is the inverse of PMIx_Data_unload(3).

The transfer is a move, not a copy: the buffer takes direct ownership of the memory referenced by payload->bytes — no new allocation is made and no byte-copy is performed. Upon successful completion the payload object is emptied — its bytes field is reset to NULL and its size field to zero — so that the caller and the buffer no longer share the same memory. Because ownership has moved into the buffer, the caller must not free payload->bytes afterward; the memory will be released when the buffer itself is destructed (e.g., with PMIX_DATA_BUFFER_DESTRUCT or PMIX_DATA_BUFFER_RELEASE).

If the buffer already holds a payload, that existing payload is first freed (the buffer is destructed and re-constructed) before the new payload is loaded. If payload is NULL, any existing buffer payload is released and the function returns leaving the buffer empty.

The caller is responsible for pre-packing the provided payload. The load function performs no serialization and cannot convert any data contained in the payload to network byte order; the payload is expected to already be in packed form, such as that produced by PMIx_Data_unload(3).

18.2.79.4. 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 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.79.5. NOTES

Use PMIx_Data_embed(3) instead when the source payload must be preserved for the caller; unlike PMIx_Data_load, embed copies the payload into the buffer and leaves the source byte object unaltered.