18.2.80. PMIx_Data_embed

PMIx_Data_embed — Embed a copy of a data payload into a buffer, preserving the source payload.

18.2.80.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Data_embed(pmix_data_buffer_t *buffer,
                              const pmix_byte_object_t *payload);

18.2.80.2. INPUT PARAMETERS

payload: Pointer to a pmix_byte_object_t(5) containing the data payload to be embedded into the buffer. The payload is treated as read-only and is not modified.

18.2.80.3. OUTPUT PARAMETERS

buffer: Pointer to the destination pmix_data_buffer_t into which a copy of the payload is placed. The buffer must have been allocated (e.g., with PMIX_DATA_BUFFER_CREATE) or constructed (e.g., with PMIX_DATA_BUFFER_CONSTRUCT) in advance.

18.2.80.4. DESCRIPTION

Embed the contents of the payload byte object into buffer so that the data can subsequently be extracted with PMIx_Data_unpack(3). The embed function is identical in operation to PMIx_Data_load(3) except that it does not clear or otherwise alter the payload upon completion.

Unlike PMIx_Data_load(3), which moves ownership of the payload’s memory into the buffer, PMIx_Data_embed copies the payload: the buffer receives an independent copy of the data, and the source payload byte object is left intact and still owned by the caller. The caller therefore remains responsible for releasing payload when it is no longer needed, and the buffer and its embedded copy are released separately when the buffer is destructed.

If the buffer already holds a payload, that existing payload is first freed (the buffer is destructed and re-constructed) before the copy is embedded. 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 embed 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.

18.2.80.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 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.80.6. NOTES

Use PMIx_Data_embed when the source payload must remain valid and owned by the caller after the operation. When the payload can be consumed and its memory handed to the buffer, PMIx_Data_load(3) avoids the copy.