Class thl::RCU#
-
template<typename T>
class RCU# Generic RCU (Read-Copy-Update) container for lock-free reads.
This template provides lock-free read access to any data structure while allowing safe updates through copy-on-write semantics. Perfect for real-time audio applications where readers (audio thread) must never block.
IMPORTANT: For real-time threads, call register_reader_thread() before entering the real-time context (e.g., during audio setup). This allocates the reader node outside the real-time path. A reader that runs on changing threads (a plugin whose host moves the render callback from thread to thread) cannot register in advance: it reads through a reader slot, add_reader() and read_scope(Reader), which never registers.
A writer publishes with update() or replace(), or in two steps: stage_update() / stage_replace() make the next version and everything its publication needs (they may throw, and then nothing has changed), commit() publishes a staged version and cannot fail. The two steps are for a change that spans several RCUs, or an RCU and state of the caller: stage all of it, then commit all of it. See Staged and commit().
- Template Parameters:
T – The type of data to protect (e.g., std::map, std::vector)
Public Types
Public Functions
-
inline explicit RCU(const T &initial_data = T{}, size_t cleanup_threshold = 8, size_t emergency_threshold = 32)#
Construct RCU with initial data.
- Parameters:
initial_data – Initial value (will be copied)
cleanup_threshold – Number of retired versions before aggressive cleanup
emergency_threshold – Number of retired versions before blocking cleanup
-
inline explicit RCU(T &&initial_data, size_t cleanup_threshold = 8, size_t emergency_threshold = 32)#
Construct RCU with moved data.
- Parameters:
initial_data – Initial value (will be moved)
cleanup_threshold – Number of retired versions before aggressive cleanup
emergency_threshold – Number of retired versions before blocking cleanup
-
inline ~RCU()#
-
template<typename Func>
inline auto read(Func &&read_func) const -> decltype(read_func(std::declval<const T&>()))# Lock-free read access.
Provides safe read access to the data structure. The provided function is called with a const reference to the current data. The data is guaranteed to remain valid for the duration of the function call.
Usage:
rcu_map.read([&](const auto& map) { auto it = map.find("key"); if (it != map.end()) { value = it->second; } });
- Parameters:
read_func – Function to call with const reference to data
-
template<typename Func>
inline void update(Func &&update_func)# Update data using copy-on-write.
Creates a copy of the current data, allows modification via the provided function, then atomically publishes the new version. This operation may block and is not real-time safe.
When it throws (an allocation that fails, or update_func) nothing was published: everything that can fail comes before the publication.
Usage:
rcu_map.update([&](auto& map) { map["new_key"] = value; map.erase("old_key"); });
- Parameters:
update_func – Function to modify the copied data
-
template<typename Func>
inline void replace(Func &&build_func)# Publish a freshly built version, without reading the current one.
Same publication and reclamation as update(), but the new version is default-constructed and filled in by build_func rather than copied from the live one. Use this when the writer rebuilds T from scratch anyway — it skips a pointless deep copy, and, more importantly, it never reads the version the readers are using. That matters when readers mutate state inside T (RT scratch state reached through a const reference, for example): update()’s copy would race with those writes, this does not.
Requires T to be default-constructible. May block; not real-time safe. When it throws (an allocation that fails, or build_func) nothing was published.
Usage:
rcu_config.replace([&](auto& config) { config.entries = std::move(freshly_built_entries); });
- Parameters:
build_func – Function that fills in the fresh, empty value
-
template<typename Func>
inline Staged stage_update(Func &&update_func)# First half of update(): make the next version from a copy of the current one, publish nothing.
Copies the current version, lets update_func modify the copy and makes the room its publication needs. Everything of a publication that can fail happens here: when this throws (std::bad_alloc, or whatever update_func throws) the RCU is as it was, readers see what they saw, and nothing is leaked. commit() publishes the returned version and cannot fail.
Like update() it reads the live version (see there) and holds the writer mutex while update_func runs; unlike update() it does not hold it afterwards. See commit() for what may happen between the two calls. May block; not real-time safe.
- Parameters:
update_func – Function to modify the copied data
-
template<typename Func>
inline Staged stage_replace(Func &&build_func)# First half of replace(): build the next version from scratch, publish nothing.
Default-constructs a T, lets build_func fill it in and makes the room its publication needs. Everything of a publication that can fail happens here: when this throws (std::bad_alloc, or whatever build_func throws) the RCU is as it was, readers see what they saw, and nothing is leaked. commit() publishes the returned version and cannot fail.
Like replace() it never reads the live version and holds the writer mutex while build_func runs; unlike replace() it does not hold it afterwards. See commit() for what may happen between the two calls. Requires T to be default-constructible. May block; not real-time safe.
Usage, two RCUs that change together:
auto table = rcu_table.stage_replace([&](auto& t) { t = build_table(); }); auto rows = rcu_rows.stage_replace([&](auto& r) { r = build_rows(); }); // ... whatever else can fail. A throw up to here leaves both RCUs alone. rcu_table.commit(std::move(table)); // noexcept from here on rcu_rows.commit(std::move(rows));
- Parameters:
build_func – Function that fills in the fresh, empty value
-
inline void commit(Staged &&staged) noexcept#
Second half of a publication in two steps: publish a staged version.
Publishes the version, retires the one it replaces and reclaims the retired versions no reader uses any more, exactly as update() / replace() do after they have built theirs. It cannot fail and allocates nothing: the retired version goes into the room its stage_update() / stage_replace() made.
stagedis empty afterwards.It blocks where update() / replace() block and nowhere else: on the writer mutex (another writer, a thread registering as a reader, add_reader(), get_reader_count(), a synchronize() in progress), and on readers only in the emergency tier, when the number of retired versions reaches the emergency threshold. Not real-time safe; like them, not to be called from inside a read section of this RCU, which that tier would wait for.
One writer from stage to commit: between a stage_update() / stage_replace() and the commit() of its result nothing else may be published in this RCU, no update(), no replace() and no commit() of another staged version. The RCU does not hold its writer mutex between the two calls (readers register, add_reader() and synchronize() go on), so keeping other writers out is the caller’s job: one writer thread, or a mutex of the caller’s around stage and commit. Under that exclusion the two calls may run on different threads. Several versions may be staged at once as long as at most one of them is committed: drop the others and stage them again.
commit() asserts the rule. A release build that breaks it still publishes
staged, but the room the stage made may be used up, so the commit may allocate (and terminates when that fails), and a version from stage_update() replaces whatever was published in between with a copy that never contained it.stagedmust be this instance’s (asserted; a release build publishes it here all the same, under the consequences above). An empty one is a contract violation too (asserted; a release build does nothing).
-
inline void register_reader_thread() const#
Register the current thread for real-time safe reads.
Call this method from any thread that will use read() before entering a real-time context. This allocates the reader node, so subsequent read() calls are allocation-free and real-time safe.
Safe to call multiple times - subsequent calls are no-ops. NOT real-time safe (allocates memory on first call per thread).
Usage:
// During audio setup (non-RT context) - preferred rcu_state.register_reader_thread(); // Or just call read() - auto-registers on first use rcu_state.read([](const auto& data) { // First call may allocate, subsequent calls are RT-safe });
Note
If not called explicitly, read() will auto-register on first use. But this first call is NOT real-time safe.
-
inline Reader add_reader() const#
Create a reader slot owned by this instance instead of by a thread.
For a reader that is one logical client but may run on changing threads, e.g. a plugin whose host calls the render callback from different threads: the per-thread registration would allocate (and lock) on the real-time path every time the thread changes. Pass the slot to read_scope(reader) instead; that path never allocates or locks.
NOT real-time safe: call once per client during setup (e.g. in a constructor, not in a host’s prepareToPlay): slots are not removed, they stay valid until this RCU is destroyed and every writer scans them.
A slot has one user at a time. That user’s scopes on the slot nest (see ReadScope); two threads must never be inside read_scope(reader) for one slot at the same time. “One after the other” means ordered by happens-before, not merely by the clock: the hand-over from one thread to the next has to go through something that orders the two, such as a host that calls its render callback from one thread after the other, a mutex, a thread join, or an atomic flag that is claimed with at least std::memory_order_acquire and given back, after the scope has closed, with at least std::memory_order_release. Nothing checks this: a slot used by two threads at once, or passed on through a relaxed flag, can read a version that the writer has already freed.
A section that is never closed (a leaked ReadScope, a thread killed inside one) blocks synchronize() for ever, and update() / replace() once enough versions are retired: a slot has no thread whose exit would release it.
-
inline unsigned int get_reader_count() const#
Number of readers a writer scans: the reader slots from add_reader() plus the registered threads that are still alive.
Takes the writer mutex: not real-time safe.
-
inline void synchronize()#
Wait until no reader is inside a read section that began before the latest publication.
When it returns, every reader (registered thread or reader slot) is outside a read section or inside one that sees the current version, so whatever only older versions referred to is no longer in use. Blocks (it polls) and takes the writer mutex: not real-time safe.
A registered thread that has exited is skipped. A reader slot whose section is never closed is waited for indefinitely. Must not be called from inside a read section of this RCU that was opened before the latest update() / replace(): the caller would wait for itself.
-
inline ReadScope read_scope(Reader reader) const#
Open a read section on a reader slot from add_reader().
Real-time safe on any thread: no registration, no allocation, no lock and no thread-local access.
The slot must have one user at a time, ordered as add_reader() describes.
readermust be this instance’s (asserted). An empty one is a contract violation too (asserted); a release build then falls back to the calling thread’s registration, which is not real-time safe on first use.
-
class Reader#
A reader slot from add_reader(): a non-owning handle, cheap to copy.
Default-constructed it is empty. It belongs to the RCU instance that made it and only opens sections there.
-
class ReadScope#
RAII scope that holds an RCU read section open.
Use when a caller needs to keep the read section open across multiple operations (e.g. wrapping a whole audio block rather than each per-sample access). Opens rcu_read_lock() in the ctor and closes it in the dtor, while exposing the current data pointer.
Non-copyable, non-movable. Must not outlive the RCU instance. Scopes on the same thread or reader slot nest: the outermost one holds the section. An inner scope may see a newer version than the outer one; each scope’s data() stays valid until the outermost scope is closed.
Usage:
// dtor releases sectionauto scope = rcu.read_scope(); // auto-registers, enters section use(scope.data()); // data() valid until dtor
Public Functions
-
inline ~ReadScope()#
-
inline ~ReadScope()#
-
class Staged#
A version made by stage_update() / stage_replace() and not yet published: the first half of a publication in two steps.
Move-only. It owns the version until commit() takes it. Destroyed without a commit it frees the version, on the destroying thread, and the RCU stays as it was; it does not touch the RCU then, so it may outlive it. No reader sees the version before commit(), so data() may still be changed.
Default-constructed or moved-from it is empty.