xtc_free(3)

---

xtc_free(3)

public allocation, clock, sleep, and atomic helpers

XTC_FREE(3) Library Functions Manual XTC_FREE(3)

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, xtc_ncpus, xtc_numa_nnodes, xtc_numa_node_of_cpu, xtc_numa_current_node — public allocation, clock, sleep, and atomic helpers

#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);

int
xtc_ncpus(void);

int
xtc_numa_nnodes(void);

int
xtc_numa_node_of_cpu(int cpu);

int
xtc_numa_current_node(void);

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

() 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():

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 () rather than plain free(3). Passing NULL is a no-op. xtc_free() is safe to call from any thread.

(), (), and () 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. () returns memory aligned to align (a power of two), released ONLY with () (never xtc_free()).

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

(), (), (), and () report CPU and NUMA topology, for a consumer that shards state per core or per node (a buffer pool, a partitioned index, a per-core free list). xtc_ncpus() is the number of usable CPUs, honoring the cgroup quota and affinity mask where the platform reports them, and is always at least 1. xtc_numa_nnodes() returns 1 on a non-NUMA or unqueryable system, in which case xtc_numa_node_of_cpu() returns 0 — so a caller may shard by the returned node with no special case. xtc_numa_current_node() is the node the CALLING thread is running on at that instant; a thread can migrate, so treat it as a placement hint rather than a stable identity. All four are cheap cached queries and safe to call from any thread.

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_ncpus() returns the usable CPU count (>= 1). xtc_numa_nnodes() returns the NUMA node count (>= 1; 1 when not NUMA or not queryable). xtc_numa_node_of_cpu() returns the node owning cpu, or 0 when the topology is unavailable. xtc_numa_current_node() returns the calling thread's current node, or 0. None of these fail.

xtc_proc(3), xtc_net(3), xtc_osproc(3), xtc_svr(3)

July 6, 2026 Debian

View the mdoc source