Template Class VersionedVariable

Class Documentation

template<typename T>
class VersionedVariable

Requires: std::copy_constructible<T> && std::assignable_from<T&, T> && std::equality_comparable<T>

Synchronizes one value and its revision as a unit.

Repeated equal sets do not advance the revision. Readers can retain a revision and wait for a later change without missing a change between reads. Comparison/copy/assignment execute under the storage mutex and must not reenter this variable. Their exceptions propagate; throwing assignment follows T’s own failure guarantee and may change a value without advancing revision/notifying. Keep the variable alive through all readers/waiters; destruction is not cancellation. The mutex makes this storage noncopyable/nonmovable; snapshots copy values instead.

Template Parameters:

T – Copyable, assignable, equality-comparable stored value type.

Public Functions

inline explicit VersionedVariable(T initial)

Publishes the initial owned value with revision zero.

Parameters:

initial – Value moved into storage; construction/copy failures propagate. No notification is emitted during construction; the object must outlive every waiter.

inline void set(T next)

Publishes a changed value and wakes waiters after unlocking.

See also

State utilities

Parameters:

next – Candidate value, copied/moved into owned storage. An equal value leaves revision unchanged. Comparison/assignment happen under the mutex and must not reenter this variable. Their exceptions propagate; a throwing assignment follows T’s guarantee and may modify value without advancing revision.

inline ::CE::State::VersionedSnapshot<T> snapshot() const

Declaration: [[nodiscard]]

Copies the value and revision under one lock.

Returns:

Independent snapshot; copying T can throw. Its pointees still follow T’s ownership. The lock is released before return and does not protect use of the returned value.

inline T get() const

Declaration: [[nodiscard]]

Copies the current value under its storage lock.

Returns:

Owned T copy; no revision or retained lock accompanies it. Copy failures propagate.

inline std::uint64_t revision() const

Declaration: [[nodiscard]]

Samples the current change revision under its storage lock.

Returns:

Unsigned revision, incremented only for a successfully assigned different value. Separate get()/revision() calls are not one atomic snapshot; use snapshot() for that.

inline ::CE::State::VersionedSnapshot<T> wait_for_change(std::uint64_t since) const

Declaration: [[nodiscard]]

Waits until the current revision differs, then copies a consistent snapshot.

Parameters:

since – Previously sampled revision; returns immediately when it already differs.

Returns:

Current owned value/revision, not every intermediate update. Notifications coalesce. There is no timeout or shutdown cancellation: keep storage alive and arrange a changed set() when waiters must finish. Copy failures propagate.