18.2.195. PMIx_Device_distance_construct

PMIx_Device_distance_construct — Initialize a caller-provided pmix_device_distance_t(5) structure.

18.2.195.1. SYNOPSIS

#include <pmix.h>

void PMIx_Device_distance_construct(pmix_device_distance_t *d);

18.2.195.1.1. Python Syntax

No Python equivalent

18.2.195.2. INPUT PARAMETERS

d: Pointer to the pmix_device_distance_t(5) structure to be initialized. The storage for the structure itself must already exist — it is supplied by the caller (typically declared on the stack or embedded within another object).

18.2.195.3. DESCRIPTION

Initialize the memory of a pmix_device_distance_t that the caller has already allocated. The function zeroes the entire structure — clearing the uuid and osname string pointers — sets the type field to PMIX_DEVTYPE_UNKNOWN, and sets both the mindist and maxdist fields to UINT16_MAX. No heap memory is allocated.

A structure must be constructed (or created with PMIx_Device_distance_create(3)) before any of its fields are used; operating on an uninitialized structure produces undefined behavior.

Because PMIx_Device_distance_construct operates on caller-provided storage, it must be paired with PMIx_Device_distance_destruct(3) to release any uuid or osname strings the structure subsequently acquires. Do not pass a constructed (as opposed to created) structure to PMIx_Device_distance_free(3), as that would attempt to free storage the library did not allocate.

18.2.195.4. RETURN VALUE

PMIx_Device_distance_construct returns no value (void).

18.2.195.5. NOTES

The mindist and maxdist fields are initialized to UINT16_MAX rather than zero, so that an unset distance is distinguishable from a valid distance of zero. Note that this differs from the PMIX_DEVICE_DIST_STATIC_INIT initializer, which sets both fields to zero.

18.2.195.6. EXAMPLES

Construct a structure:

pmix_device_distance_t dist;

PMIx_Device_distance_construct(&dist);