xtc_free(3)

---

xtc_free(3)

public allocation, clock, sleep, and atomic helpers

XTC_FREE(3)

Library Functions Manual

XTC_FREE(3)

NAME

xtc_free, xtc_malloc, xtc_calloc, xtc_realloc, xtc_aligned_alloc, xtc_aligned_free, xtc_clock_mono, xtc_clock_real, xtc_sleep_ns, xtc_atomic_i64_load, xtc_atomic_i64_add — public allocation, clock, sleep, and atomic helpers

SYNOPSIS

#include <xtc.h>

void
xtc_free(void *p);

void *
xtc_malloc(size_t size);

void *
xtc_calloc(size_t n, size_t size);

void *
xtc_realloc(void *p, size_t size);

void *
xtc_aligned_alloc(size_t align, size_t size);

void
xtc_aligned_free(void *p);

int64_t
xtc_clock_mono(void);

int64_t
xtc_clock_real(void);

int
xtc_sleep_ns(int64_t ns);

int64_t
xtc_atomic_i64_load(const int64_t *p);

int64_t
xtc_atomic_i64_add(int64_t *p, int64_t delta);

DESCRIPTION

These are the public complement to the library's internal portability layer: a CONSUMER of libxtc uses only these xtc_*() entry points and never the internal __os_*() wrappers.

xtc_free() releases a heap buffer that a libxtc call allocated and handed to the caller to own. Several APIs return caller-owned buffers and document that they must be released with xtc_free():

the message buffer from xtc_recv(3), xtc_recv_match(), and xtc_recv_correlate();
the frame from xtc_net_recv_frame();
the reply buffer from xtc_osproc_call() and xtc_svr_call().

These buffers are allocated by libxtc's own allocator, which is not necessarily the C library malloc(3)/free(3), so they must be released through xtc_free() rather than plain free(3). Passing NULL is a no-op. xtc_free() is safe to call from any thread.

xtc_malloc(), xtc_calloc(), and xtc_realloc() allocate through libxtc's allocator (the same one xtc_free() releases, overridable via the allocator hook), returning the pointer directly and NULL on failure; the result is released with xtc_free(). A zero size yields a unique freeable pointer, not NULL. xtc_aligned_alloc() returns memory aligned to align (a power of two), released ONLY with xtc_aligned_free() (never xtc_free()).

xtc_clock_mono() and xtc_clock_real() read the monotonic and real clocks in nanoseconds (returning 0 on the rare query failure). xtc_sleep_ns() sleeps the calling OS THREAD; inside a fiber use xtc_proc_sleep(3) instead, which parks the fiber without blocking the loop. xtc_atomic_i64_load() and xtc_atomic_i64_add() (which returns the prior value) are the minimal public atomics for a shared 64-bit counter.

RETURN VALUES

xtc_free() and xtc_aligned_free() return no value. xtc_malloc(), xtc_calloc(), xtc_realloc(), and xtc_aligned_alloc() return the allocated pointer, or NULL on failure. xtc_clock_mono() and xtc_clock_real() return a nanosecond count (0 on failure). xtc_sleep_ns() returns XTC_OK or a negative XTC_E_* code. xtc_atomic_i64_load() returns the current value; xtc_atomic_i64_add() returns the value before the add.

xtc_free(3)

xtc_free(3)

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

SEE ALSO