GGUI::MutationQueue class
#include <GGUI/Public/MutationQueue.h>

Changes to a node tree requested from any thread, applied by the UI update. See the file description.

Public static variables

static size_t InlineBytes constexpr
Max size of an Invoke callable, captures included.

Public functions

auto Initialize(size_t capacity, BufferPool* pool = nullptr) -> bool
capacity is rounded up to a power of two. pool supplies InvokeWith buffers (null: the process-wide MemPool). Call from the UI update thread before any other use.
auto AllocateBuffer(size_t bytes) -> PooledBuffer
A buffer to fill and pass to InvokeWith. Empty if the pool is exhausted. Any thread.
auto Destroy(NodeHandle node) -> bool
Destroy node and what it holds.
auto AppendChild(NodeHandle parent, NodeHandle child) -> bool
Make child the last child of parent, moving it from where it was.
auto InsertBefore(NodeHandle parent, NodeHandle child, NodeHandle before) -> bool
Put child among parent's children before before.
auto Remove(NodeHandle child) -> bool
Take child out of its parent, keeping it.
template<typename TFn>
auto Invoke(TFn fn) -> bool
Run fn(NodeStorage&) in the UI update, ordered with this thread's other requests.
template<typename TFn>
auto InvokeWith(PooledBuffer buffer, TFn fn) -> bool
Invoke with a data buffer: fn(NodeStorage&, std::span<std::byte>).
auto Apply(NodeStorage& storage) -> uint32_t
Apply everything queued, in order. Returns the number of requests consumed.
auto AppliedCount() const -> uint64_t
Requests applied.
auto RejectedCount() const -> uint64_t
Rejected at apply time (stale handle, invalid move).
auto DroppedCount() const -> uint64_t
Lost because the queue was full.

Function documentation

template<typename TFn>
bool GGUI::MutationQueue::Invoke(TFn fn)

Run fn(NodeStorage&) in the UI update, ordered with this thread's other requests.

The callable is copied into the queue: it must be trivially copyable and fit InlineBytes. Capture handles and values, never references to locals.

template<typename TFn>
bool GGUI::MutationQueue::InvokeWith(PooledBuffer buffer, TFn fn)

Invoke with a data buffer: fn(NodeStorage&, std::span<std::byte>).

The queue releases the buffer after the call. If the request can't be queued (queue full, or buffer empty), the buffer is released and false is returned.