SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
Loading...
Searching...
No Matches
stk_sync_barrier.h
Go to the documentation of this file.
1/*
2 * SuperTinyKernel(TM) RTOS: Lightweight High-Performance Deterministic C++ RTOS for Embedded Systems.
3 *
4 * Source: https://github.com/SuperTinyKernel-RTOS
5 *
6 * Copyright (c) 2022-2026 Neutron Code Limited <stk@neutroncode.com>. All Rights Reserved.
7 * License: MIT License, see LICENSE for a full text.
8 */
9
10#ifndef STK_SYNC_BARRIER_H_
11#define STK_SYNC_BARRIER_H_
12
13#include "stk_sync_mutex.h"
14#include "stk_sync_cv.h"
15
19
20namespace stk {
21namespace sync {
22
54class Barrier final : public ITraceable
55{
56public:
75
80 explicit Barrier(uint32_t count) : m_threshold(count), m_count(count), m_generation(0U)
81 {
82 STK_ASSERT(count != 0U); // API contract: number of parties cannot be 0
83 }
84
89
101 bool Wait() { return (WaitEx() == BARRIER_LAST_ARRIVAL); }
102
113 EResult WaitEx();
114
118 uint32_t GetThreshold() const { return m_threshold; }
119
120private:
122
125 const uint32_t m_threshold;
126 uint32_t m_count;
127 uint32_t m_generation;
128};
129
130// ---------------------------------------------------------------------------
131// WaitEx
132// ---------------------------------------------------------------------------
133
135{
136 EResult result = BARRIER_RELEASED;
137
138 STK_ASSERT(!hw::IsInsideISR()); // API contract: caller must not be in ISR
139
140 m_mutex.Lock();
141
142 const uint32_t gen = m_generation;
143
144 if (--m_count == 0U)
145 {
146 // last task to arrive: start a new generation and release everyone else
147 ++m_generation;
149
150 m_cond.NotifyAll();
151
152 result = BARRIER_LAST_ARRIVAL;
153 }
154 else
155 {
156 // wait in a loop to guard against spurious wakeups: keep waiting while
157 // we are still in the same generation we entered with
158 while (gen == m_generation)
159 {
160 const EWaitResult wr = m_cond.WaitEx(m_mutex, WAIT_INFINITE);
161
162 if (wr != WAIT_RESULT_SIGNAL)
163 {
164 // cancellation or kernel failure (e.g. scheduler locked): the wait did not block, so the loop
165 // must not retry (it would spin forever). The cancel wakes this task before m_mutex is
166 // re-acquired, so the barrier may have tripped in between (the trip has then already consumed
167 // our arrival and reset m_count): signal wins, report a normal release and leave the count alone
168 if (gen == m_generation)
169 {
170 // bail out before the barrier tripped: undo our own arrival so the count
171 // stays consistent for whichever tasks remain in this generation - do NOT
172 // let the barrier trip short-handed on our behalf
173 ++m_count;
175 }
176
177 break;
178 }
179 // else: WAIT_RESULT_SIGNAL - NotifyAll() always pairs with ++m_generation, so a
180 // genuine signal here means gen != m_generation already and the loop exits next check
181 }
182 }
183
184 m_mutex.Unlock();
185
186 return result;
187}
188
189} // namespace sync
190} // namespace stk
191
192#endif /* STK_SYNC_BARRIER_H_ */
#define STK_NONCOPYABLE_CLASS(TYPE)
Deletes (= delete) the copy constructor and copy assignment operator of a class.
Definition stk_defs.h:708
#define STK_ASSERT(e)
Runtime assertion. Halts execution if the expression e evaluates to false.
Definition stk_defs.h:532
#define STK_VIRT_DTOR
Expands to nothing if STK_STRICT_COMPLIANCY=0 (non-virtual destructors, smaller objects),...
Definition stk_defs.h:254
Implementation of synchronization primitive: stk::sync::ConditionVariable.
Implementation of synchronization primitive: stk::sync::Mutex.
Namespace of STK package.
EWaitResult
Wait result (see IKernelService::Wait).
Definition stk_common.h:138
@ WAIT_RESULT_CANCELED
The wait was cancelled by another task via IKernel::CancelTaskWait(), independent of signal/timeout.
Definition stk_common.h:142
@ WAIT_RESULT_SIGNAL
The wake was caused by a signal.
Definition stk_common.h:140
static constexpr Timeout WAIT_INFINITE
Timeout value: block indefinitely until the synchronization object is signaled.
Definition stk_common.h:274
bool IsInsideISR()
Check whether the CPU is currently executing inside a hardware interrupt service routine (ISR).
Synchronization primitives for task coordination and resource protection.
Traceable object.
Definition stk_common.h:606
uint32_t m_count
number of tasks still to arrive in the current generation
Barrier(uint32_t count)
Constructor.
uint32_t GetThreshold() const
Get the number of tasks required to trip the barrier.
ConditionVariable m_cond
signals waiting tasks when the current generation completes
uint32_t m_generation
generation counter, incremented every time the barrier trips
bool Wait()
Block the calling task until count tasks have called Wait().
EResult
Outcome of a Barrier::WaitEx() call.
@ BARRIER_LAST_ARRIVAL
This task was the last arrival and tripped the barrier.
@ BARRIER_RELEASED
Released because the barrier tripped; this task was not the last arrival.
const uint32_t m_threshold
number of tasks required to trip the barrier
Mutex m_mutex
protects m_count / m_generation and serializes calls to m_cond
EResult WaitEx()
Block the calling task until count tasks have called Wait(), preserving the full outcome.
Condition Variable primitive for signaling between tasks based on specific predicates.
Definition stk_sync_cv.h:68
Recursive mutex primitive that allows the same thread to acquire the lock multiple times.