18.3.16. pmix_data_buffer_t

pmix_data_buffer_t — Describes a data buffer used for packing and unpacking

18.3.16.1. SYNTAX

18.3.16.1.1. C Syntax

#include <pmix_common.h>

typedef struct pmix_data_buffer {
    /** Start of my memory */
    char *base_ptr;
    /** Where the next data will be packed to (within the allocated
        memory starting at base_ptr) */
    char *pack_ptr;
    /** Where the next data will be unpacked from (within the
        allocated memory starting as base_ptr) */
    char *unpack_ptr;
    /** Number of bytes allocated (starting at base_ptr) */
    size_t bytes_allocated;
    /** Number of bytes used by the buffer (i.e., amount of data --
        including overhead -- packed in the buffer) */
    size_t bytes_used;
} pmix_data_buffer_t;

18.3.16.2. DESCRIPTION

The pmix_data_buffer_t structure describes a data buffer used for packing and unpacking of PMIx data. It provides an opaque, self-describing container into which typed data can be serialized (packed) for transmission or storage, and from which that data can subsequently be deserialized (unpacked).

The structure carries the following fields:

base_ptr — Pointer to the start of the memory region allocated for the buffer.
pack_ptr — Pointer to the location, within the memory region starting at base_ptr, at which the next data element will be packed.
unpack_ptr — Pointer to the location, within the memory region starting at base_ptr, from which the next data element will be unpacked.
bytes_allocated — The number of bytes allocated for the buffer, starting at base_ptr.
bytes_used — The number of bytes used by the buffer — that is, the amount of data (including overhead) currently packed in the buffer.

Callers should treat these fields as opaque and manipulate a pmix_data_buffer_t only through the provided support routines rather than by directly accessing or modifying the fields. A statically declared pmix_data_buffer_t may be initialized using the PMIX_DATA_BUFFER_STATIC_INIT initializer.

18.3.16.3. SUPPORT FUNCTIONS

PMIx provides a number of functions and macros to support constructing, destructing, allocating, releasing, loading, and unloading pmix_data_buffer_t structures, along with packing and unpacking their contents. These include:

PMIX_DATA_BUFFER_CREATE — Allocate and initialize a pmix_data_buffer_t object.
PMIX_DATA_BUFFER_RELEASE — Free a pmix_data_buffer_t object and the data it contains.
PMIX_DATA_BUFFER_CONSTRUCT — Initialize the fields of a statically declared pmix_data_buffer_t.
PMIX_DATA_BUFFER_DESTRUCT — Release the data held by a pmix_data_buffer_t (the companion to PMIX_DATA_BUFFER_CONSTRUCT).
PMIX_DATA_BUFFER_LOAD / PMIX_DATA_BUFFER_UNLOAD — Load a region of memory into, or extract it from, a pmix_data_buffer_t.
PMIx_Data_pack — Pack one or more values of a given type into a pmix_data_buffer_t.
PMIx_Data_unpack — Unpack one or more values of a given type from a pmix_data_buffer_t.

pmix_data_buffer_t is the buffer type manipulated by the PMIx_Data_pack, PMIx_Data_unpack, and PMIx_Data_buffer_* interfaces.

18.3.16.4. STATIC INITIALIZER

A statically declared pmix_data_buffer_t may be initialized with the PMIX_DATA_BUFFER_STATIC_INIT macro, which sets the base_ptr, pack_ptr, and unpack_ptr pointers to NULL and both bytes_allocated and bytes_used to 0:

pmix_data_buffer_t buffer = PMIX_DATA_BUFFER_STATIC_INIT;