tls_slot<T>
include/reloco/tls_slot.hpp
A thread-local cell for an object that is more than plain bytes: it has a constructor that may allocate and
fail, and a destructor that must run when the thread exits. It is the C++ side of kif’s static thread cells
(docs/kif-proc-language.md §4.17), and works by itself in any C++ code.
Why it exists
Thread-local storage in a kernel cannot rely on the C++ runtime: there are no TLS constructors, memory may be
exhausted, and a thread may start with a block of zeroes. tls_slot therefore has three rules:
- Zero is valid. A slot in all-zero memory is empty. Put it in a zero-filled block and it works, with no constructor having run.
- Built lazily, fallibly.
try_withbuilds the object on first use. The initialiser returnsresult<T>, may allocate, and its error is returned to the caller; the slot stays empty and can be retried. - Destroyed by its owner. The destructor of the slot is trivial. The block that owns it calls
destroy()at thread exit (kif generates that call).
API
| Member | Meaning |
|---|---|
try_with(init, f) / try_with_mut(init, f) |
Build if empty, then run f(const T &) / f(T &). RELOCO_MIGHT_SLEEP. Returns result<R>; error::busy if called from inside init for the same slot. |
with_ready(f) / with_ready_mut(f) |
Run f only if the slot is ready, never initialises. Returns optional<R>, or bool for a void closure. Usable where sleeping is not allowed. |
destroy() |
Run T’s destructor if ready, then become empty. Idempotent. Must not run while a closure of the slot executes. |
is_ready() |
Whether the object exists. |
Closures must not return a reference or a pointer (the object is only borrowed for the call).
Example
#include <reloco/tls_provider.hpp>
#include <reloco/tls_slot.hpp>
#include <reloco/vector.hpp>
// A thread's scratch buffer: it allocates, so it is built lazily and can fail.
using scratch = reloco::vector<int>;
reloco::result<scratch> make_scratch() noexcept { // init_fn: result<T>(*)() noexcept
scratch v;
RELOCO_TRY(v.try_reserve(64)); // may fail with resource_exhausted
return v;
}
// One block per module: every slot of the module lives here, so the OS needs a single TLS key per module.
struct module_block {
reloco::tls_slot<scratch> scratch_slot; // zero == empty
};
struct module_tag {}; // distinguishes this module's block
reloco::result<void> record(int sample) noexcept {
auto block = reloco::tls_provider<module_block, module_tag>::get(); // zero-filled per thread on first use
RELOCO_TRY(block);
return block->get().scratch_slot.try_with_mut(&make_scratch, // init: runs only when empty
[&](scratch &v) noexcept { return v.try_push_back(sample); }); // f: runs with the object
}
void thread_exit() noexcept { // the owner of the block destroys its slots
if (auto block = reloco::tls_provider<module_block, module_tag>::get(); block.has_value()) {
block->get().scratch_slot.destroy();
}
}
Integration
tls_providersupplies the per-thread, zero-filled block (RELOCO_TLS_MODEL:thread_local, pthread keys, a custom OS backend, or single-threaded).tls_slotadds no provider of its own.- Thread exit. Call
destroy()on every slot of the block from the thread-exit hook of your target (on FreeBSD, anosd_thread_register(9)destructor). The hook of a new thread must not rely on any slot being ready. - kif.
static threadcells lower to amodule_blockper module plus atls_slot<T>field per cell, and a generated exit hook that callsdestroy(). Adropof a TLS cell must not reach another TLS cell (KIFP183).
Tests
tests/test_tls_slot.cpp.