MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
ControlSnapshot.hpp
Go to the documentation of this file.
1#pragma once
2
4
5namespace MayaFlux {
6
7/**
8 * @class ControlSnapshot
9 * @brief One pending value of any copyable type, such as a string or a list, set from any thread.
10 *
11 * The counterpart of ControlValue for what does not fit six double lanes. A
12 * value is published as one immutable snapshot, so a reader never sees it half
13 * written, and a later value replaces one that nothing has applied yet. The
14 * consumer takes it once per change with pending(), or reads the current one
15 * with value(). It satisfies ControlSlot, so a ControlValueStore can hold it,
16 * but not NumericControlSlot, so it has no named number access.
17 *
18 * @tparam T A copyable value type.
19 */
20template <typename T>
22public:
23 ControlSnapshot() = default;
24
25 explicit ControlSnapshot(T initial) { set(std::move(initial)); }
26
27 ControlSnapshot(const ControlSnapshot& other) { copy_state(other); }
28
30 {
31 if (this != &other) {
32 copy_state(other);
33 }
34 return *this;
35 }
36
38
40 {
41 if (this != &other) {
42 copy_state(other);
43 }
44 return *this;
45 }
46
47 ~ControlSnapshot() = default;
48
49 /** @brief True once a value was given. */
50 [[nodiscard]] bool has_value() const noexcept { return m_set.load(std::memory_order_acquire); }
51
52 /** @brief The current value, or null when none was given. */
53 [[nodiscard]] std::shared_ptr<const T> value() const noexcept
54 {
55 const auto view = m_cell.read();
56 return view ? *view : nullptr;
57 }
58
59 /** @brief True when a consumer should apply this value now. */
60 [[nodiscard]] bool due() const noexcept
61 {
62 return has_value() && m_dirty.load(std::memory_order_acquire);
63 }
64
65 /** @brief Marks the current value as applied. */
66 void settle() noexcept { m_dirty.exchange(false, std::memory_order_acq_rel); }
67
68 /** @brief The value to apply now, or null when nothing is due. A value is returned once per change. */
69 [[nodiscard]] std::shared_ptr<const T> pending() noexcept
70 {
71 if (!has_value() || !m_dirty.exchange(false, std::memory_order_acq_rel)) {
72 return nullptr;
73 }
74 return value();
75 }
76
77 /** @brief Replaces the value, so the next due() is true. */
78 void set(T value)
79 {
80 m_cell.publish(std::make_shared<const T>(std::move(value)));
81 m_set.store(true, std::memory_order_release);
82 m_dirty.store(true, std::memory_order_release);
83 }
84
85 /** @brief Takes the value @p incoming holds, so the next due() is true. */
86 void assign(const ControlSnapshot& incoming)
87 {
88 const auto view = incoming.m_cell.read();
89 if (view) {
90 m_cell.publish(*view);
91 m_set.store(true, std::memory_order_release);
92 }
93 m_dirty.store(true, std::memory_order_release);
94 }
95
96 /** @brief Nothing to read from a source. */
97 void refresh() noexcept { }
98
99private:
100 void copy_state(const ControlSnapshot& other)
101 {
102 const auto view = other.m_cell.read();
103 if (view) {
104 m_cell.publish(*view);
105 }
106 m_set.store(other.m_set.load(std::memory_order_acquire), std::memory_order_release);
107 m_dirty.store(other.m_dirty.load(std::memory_order_acquire), std::memory_order_release);
108 }
109
111 std::atomic<bool> m_set { false };
112 std::atomic<bool> m_dirty { false };
113};
114
115}
std::atomic< bool > m_dirty
std::shared_ptr< const T > value() const noexcept
The current value, or null when none was given.
ControlSnapshot(const ControlSnapshot &other)
void assign(const ControlSnapshot &incoming)
Takes the value incoming holds, so the next due() is true.
void refresh() noexcept
Nothing to read from a source.
void set(T value)
Replaces the value, so the next due() is true.
ControlSnapshot(ControlSnapshot &&other)
ControlSnapshot & operator=(ControlSnapshot &&other)
bool has_value() const noexcept
True once a value was given.
ControlSnapshot & operator=(const ControlSnapshot &other)
Memory::SnapshotCell< std::shared_ptr< const T > > m_cell
bool due() const noexcept
True when a consumer should apply this value now.
void settle() noexcept
Marks the current value as applied.
std::shared_ptr< const T > pending() noexcept
The value to apply now, or null when nothing is due.
void copy_state(const ControlSnapshot &other)
Guard read() const noexcept
Pins the current snapshot.
Lock-free cell holding one immutable snapshot of a value, read without blocking.
Main namespace for the Maya Flux audio engine.