MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
ControlValue.hpp
Go to the documentation of this file.
1#pragma once
2
4
5#include <glm/vec2.hpp>
6#include <glm/vec3.hpp>
7#include <glm/vec4.hpp>
8
9namespace MayaFlux {
10
11/**
12 * @class ControlValue
13 * @brief One pending value, written from any thread and applied once per change by one consumer.
14 *
15 * Holds a number, a bool, an enum, a float glm vector or a box (a struct of
16 * exactly a glm::vec3 `min` and a glm::vec3 `max`) as six double lanes, a width
17 * and flags. Numbers are atomic, and a vector is written and read under a
18 * sequence lock, so it is never seen half written. A value is never lost to a
19 * race, only possibly applied twice with the same content. It holds one pending
20 * value, so a later value replaces one that no block has applied yet. Integers
21 * are carried exactly up to 2^53. A read of another type than was set finds nothing.
22 */
24public:
25 template <typename T>
26 static constexpr bool is_vector = requires {
27 requires GlmVectorType<T>;
28 requires std::same_as<glm_component_type<T>, float>;
29 };
30
31 template <typename T>
32 static constexpr bool is_box = requires(T box) {
33 requires std::same_as<decltype(box.min), glm::vec3>;
34 requires std::same_as<decltype(box.max), glm::vec3>;
35 } && sizeof(T) == 2 * sizeof(glm::vec3);
36
37 template <typename T>
38 static constexpr bool is_value = std::is_arithmetic_v<T> || std::is_enum_v<T> || is_vector<T> || is_box<T>;
39
40 ControlValue() = default;
41
42 template <typename T>
43 requires is_value<T>
44 explicit ControlValue(T value) noexcept
45 {
47 m_dirty.store(true, std::memory_order_release);
48 }
49
50 ControlValue(const ControlValue& other) noexcept { copy_state(other); }
51
52 ControlValue(ControlValue&& other) noexcept { copy_state(other); }
53
54 ControlValue& operator=(const ControlValue& other) noexcept
55 {
56 if (this != &other) {
57 copy_state(other);
58 }
59 return *this;
60 }
61
63 {
64 if (this != &other) {
65 copy_state(other);
66 }
67 return *this;
68 }
69
70 ~ControlValue() = default;
71
72 /** @brief True once a value was given. */
73 [[nodiscard]] bool has_value() const noexcept { return m_set.load(std::memory_order_acquire); }
74
75 /** @brief Components held: 0 when empty, 1 for a number, flag or enum, 2 to 4 for a vector, 6 for a box. */
76 [[nodiscard]] size_t width() const noexcept { return m_width.load(std::memory_order_acquire); }
77
78 /** @brief The value as a double. */
79 [[nodiscard]] double value() const noexcept { return m_lane[0].load(std::memory_order_relaxed); }
80
81 /** @brief The value as type T, which must be the type it was set with. */
82 template <typename T>
83 requires is_value<T>
84 [[nodiscard]] T value() const noexcept
85 {
87 }
88
89 operator double() const noexcept { return value(); }
90
91 /** @brief True when a consumer should apply this value now. */
92 [[nodiscard]] bool due() const noexcept { return has_value() && changed(); }
93
94 /** @brief Marks the current value as applied. Call before reading value(). */
95 void settle() noexcept { m_dirty.exchange(false, std::memory_order_acq_rel); }
96
97 /**
98 * @brief The value to apply now as type T, or nullopt when nothing is due.
99 *
100 * A value is returned once per change. A value set with another type than T
101 * returns nothing.
102 */
103 template <typename T = double>
104 requires is_value<T>
105 [[nodiscard]] std::optional<T> pending() noexcept
106 {
107 if (!has_value() || m_width.load(std::memory_order_acquire) != width_of<T>()) {
108 return std::nullopt;
109 }
110 if (!m_dirty.exchange(false, std::memory_order_acq_rel)) {
111 return std::nullopt;
112 }
113 return from_lanes<T>(lanes_for<T>());
114 }
115
116 /** @brief Nothing to read for a plain value. A holder with a source hides this. */
117 void refresh() noexcept { }
118
119 /** @brief Takes everything @p incoming holds, so the next due() is true. */
120 void assign(const ControlValue& incoming) noexcept
121 {
122 const State state = incoming.read_state();
123 store(state.lanes, state.width, true);
124 m_dirty.store(true, std::memory_order_release);
125 }
126
127 /** @brief Shows the value the owner really has. */
128 template <typename T>
129 requires is_value<T>
130 void observe(T actual) noexcept
131 {
132 store(to_lanes(actual), width_of<T>(), true);
133 }
134
135protected:
136 static constexpr size_t k_lanes = 6;
137
138 template <typename T>
139 static constexpr uint8_t width_of() noexcept
140 {
141 if constexpr (is_vector<T>) {
142 return static_cast<uint8_t>(glm_component_count<T>());
143 } else if constexpr (is_box<T>) {
144 return 6;
145 } else {
146 return 1;
147 }
148 }
149
150 [[nodiscard]] bool changed() const noexcept { return m_dirty.load(std::memory_order_acquire); }
151
152 /** @brief Marks the slot set with one zero lane and leaves it clean. */
153 void set_blank() noexcept { store({}, 1, true); }
154
155 void set_scalar(double value) noexcept { m_lane[0].store(value, std::memory_order_relaxed); }
156
157private:
158 struct State {
159 std::array<double, k_lanes> lanes {};
160 uint8_t width {};
161 bool set {};
162 };
163
164 template <typename T>
165 static std::array<double, k_lanes> to_lanes(T value) noexcept
166 {
167 std::array<double, k_lanes> lanes {};
168 if constexpr (is_vector<T>) {
169 for (size_t index = 0; index < glm_component_count<T>(); ++index) {
170 lanes[index] = value[static_cast<glm::length_t>(index)];
171 }
172 } else if constexpr (is_box<T>) {
173 lanes = { value.min.x, value.min.y, value.min.z, value.max.x, value.max.y, value.max.z };
174 } else if constexpr (std::is_enum_v<T>) {
175 lanes[0] = static_cast<double>(static_cast<std::underlying_type_t<T>>(value));
176 } else {
177 lanes[0] = static_cast<double>(value);
178 }
179 return lanes;
180 }
181
182 template <typename T>
183 static T from_lanes(const std::array<double, k_lanes>& lanes) noexcept
184 {
185 if constexpr (is_vector<T>) {
186 T vector {};
187 for (size_t index = 0; index < glm_component_count<T>(); ++index) {
188 vector[static_cast<glm::length_t>(index)] = static_cast<float>(lanes[index]);
189 }
190 return vector;
191 } else if constexpr (is_box<T>) {
192 T box {};
193 box.min = { static_cast<float>(lanes[0]), static_cast<float>(lanes[1]), static_cast<float>(lanes[2]) };
194 box.max = { static_cast<float>(lanes[3]), static_cast<float>(lanes[4]), static_cast<float>(lanes[5]) };
195 return box;
196 } else if constexpr (std::is_enum_v<T>) {
197 return static_cast<T>(static_cast<std::underlying_type_t<T>>(lanes[0]));
198 } else if constexpr (std::same_as<T, bool>) {
199 return lanes[0] != 0.0;
200 } else {
201 return static_cast<T>(lanes[0]);
202 }
203 }
204
205 template <typename T>
206 [[nodiscard]] std::array<double, k_lanes> lanes_for() const noexcept
207 {
208 if constexpr (width_of<T>() == 1) {
209 return { m_lane[0].load(std::memory_order_relaxed), 0.0, 0.0, 0.0 };
210 } else {
211 return read_state().lanes;
212 }
213 }
214
215 [[nodiscard]] State read_state() const noexcept
216 {
217 return Memory::seqlock_read(m_lock, 0, [this] {
218 State state;
219 for (size_t index = 0; index < k_lanes; ++index) {
220 state.lanes[index] = m_lane[index].load(std::memory_order_relaxed);
221 }
222 state.width = m_width.load(std::memory_order_relaxed);
223 state.set = m_set.load(std::memory_order_relaxed);
224 return state;
225 }).value();
226 }
227
228 void store(const std::array<double, k_lanes>& lanes, uint8_t width, bool set) noexcept
229 {
231 for (size_t index = 0; index < k_lanes; ++index) {
232 m_lane[index].store(lanes[index], std::memory_order_relaxed);
233 }
234 m_width.store(width, std::memory_order_release);
235 m_set.store(set, std::memory_order_release);
236 }
237
238 void copy_state(const ControlValue& other) noexcept
239 {
240 const State state = other.read_state();
241 store(state.lanes, state.width, state.set);
242 m_dirty.store(other.m_dirty.load(std::memory_order_acquire), std::memory_order_release);
243 }
244
246 std::array<std::atomic<double>, k_lanes> m_lane {};
247 std::atomic<uint8_t> m_width { 0 };
248 std::atomic<bool> m_set { false };
249 std::atomic<bool> m_dirty { false };
250};
251
252}
bool has_value() const noexcept
True once a value was given.
static constexpr uint8_t width_of() noexcept
static T from_lanes(const std::array< double, k_lanes > &lanes) noexcept
double value() const noexcept
The value as a double.
bool changed() const noexcept
void set_scalar(double value) noexcept
State read_state() const noexcept
ControlValue & operator=(ControlValue &&other) noexcept
T value() const noexcept
The value as type T, which must be the type it was set with.
static std::array< double, k_lanes > to_lanes(T value) noexcept
void set_blank() noexcept
Marks the slot set with one zero lane and leaves it clean.
ControlValue & operator=(const ControlValue &other) noexcept
static constexpr bool is_box
ControlValue(T value) noexcept
static constexpr bool is_value
std::atomic< uint8_t > m_width
std::array< std::atomic< double >, k_lanes > m_lane
std::array< double, k_lanes > lanes_for() const noexcept
static constexpr size_t k_lanes
std::atomic< bool > m_dirty
ControlValue(ControlValue &&other) noexcept
static constexpr bool is_vector
size_t width() const noexcept
Components held: 0 when empty, 1 for a number, flag or enum, 2 to 4 for a vector, 6 for a box.
void store(const std::array< double, k_lanes > &lanes, uint8_t width, bool set) noexcept
std::atomic< bool > m_set
ControlValue(const ControlValue &other) noexcept
void observe(T actual) noexcept
Shows the value the owner really has.
void assign(const ControlValue &incoming) noexcept
Takes everything incoming holds, so the next due() is true.
bool due() const noexcept
True when a consumer should apply this value now.
void settle() noexcept
Marks the current value as applied.
void refresh() noexcept
Nothing to read for a plain value.
std::optional< T > pending() noexcept
The value to apply now as type T, or nullopt when nothing is due.
void copy_state(const ControlValue &other) noexcept
Sequence lock for fixed-size data regions.
Definition SeqLock.hpp:38
Scope guard for a serialized Seqlock write.
Definition SeqLock.hpp:178
auto seqlock_read(const Seqlock &lock, uint32_t max_attempts, Fn &&fn) -> std::optional< std::invoke_result_t< Fn > >
Invoke a read functor under a Seqlock with a bounded retry count.
Definition SeqLock.hpp:231
Main namespace for the Maya Flux audio engine.
std::array< double, k_lanes > lanes