xtc_stack_reclaim(3)
---xtc_stack_reclaim(3)
reclaim a parked fiber’s unused stack memory
| XTC_STACK_RECLAIM(3) | Library Functions Manual | XTC_STACK_RECLAIM(3) |
NAME
xtc_stack_reclaim_enable,
xtc_stack_reclaim_disable,
xtc_stack_reclaim_enabled,
xtc_stack_reclaim_count —
reclaim a parked fiber's unused stack memory
SYNOPSIS
#include
<xtc_async.h>
int
xtc_stack_reclaim_enable(size_t
keep_bytes);
void
xtc_stack_reclaim_disable(void);
int
xtc_stack_reclaim_enabled(void);
uint64_t
xtc_stack_reclaim_count(void);
DESCRIPTION
A parked stackful fiber commits only the pages it has touched, but
its mmap'd stack reserves the full configured size
(xtc_set_stack_size(3)). With reclamation enabled, a fiber
that parks (via
xtc_yield(),
which the receive, latch, and timer park paths route through) returns the
unused tail of its stack -- the region below its current stack pointer,
beyond a small live margin, page-aligned -- to the operating system with
madvise(MADV_DONTNEED).
The pages fault back as zero-fill on resume. This lowers the
per-parked-fiber memory floor for the many-idle-fiber case. It is
predictable: no relocation, no garbage collection, no segmented-stack
thrash.
xtc_stack_reclaim_enable()
turns reclamation on process-wide; keep_bytes is the
live margin left mapped below the saved stack pointer, and
0 selects a one-page default. Reclamation fires only
when the reclaimable span exceeds a page, so shallow, frequently-woken
fibers are not churned.
xtc_stack_reclaim_disable()
turns it off;
xtc_stack_reclaim_enabled()
reports the current state; and
xtc_stack_reclaim_count()
reports how many reclaim calls have been made (telemetry). Reclamation is
OFF by default: the cooperative fast path is unchanged unless it is
enabled.
SCOPE
The reclaimed region is exactly [stack_base, park_SP]: the portion below the parked fiber's stack pointer (stacks grow down, so that is the not-yet-descended-into region). The benefit is realized for a fiber whose committed stack high-water sits below where it parks -- for example a handler that recurses deep during parsing or planning, returns, then parks shallow awaiting I/O. A fiber that parks at its deepest point has little below its stack pointer to reclaim; the pages between the park point and the stack top are live and are not reclaimed while parked. For extreme fan-in where even that floor is too much, the stackless Isolate layer (xtc_tnt(3)) is the better tool; the framework offers both models deliberately.
RETURN VALUES
xtc_stack_reclaim_enable() returns
XTC_OK, or XTC_E_NOSYS where
madvise(MADV_DONTNEED) is
unavailable (for example Windows), where reclamation is a documented
no-op.
SEE ALSO
| July 5, 2026 | Debian |