stk_sync_barrier.h

Go to the documentation of this file.

/*
 * SuperTinyKernel(TM) RTOS: Lightweight High-Performance Deterministic C++ RTOS for Embedded Systems.
 *
 * Source: https://github.com/SuperTinyKernel-RTOS
 *
 * Copyright (c) 2022-2026 Neutron Code Limited <stk@neutroncode.com>. All Rights Reserved.
 * License: MIT License, see LICENSE for a full text.
 */
 
#ifndef STK_SYNC_BARRIER_H_
#define STK_SYNC_BARRIER_H_
 
#include "stk_sync_mutex.h"
#include "stk_sync_cv.h"

 
namespace stk {
namespace sync {

class Barrier final : public ITraceable
{
public:
    enum EResult : uint8_t
    {
        BARRIER_RELEASED,     
        BARRIER_LAST_ARRIVAL, 
        BARRIER_CANCELED      
    };

    explicit Barrier(uint32_t count) : m_threshold(count), m_count(count), m_generation(0U)
    {
        STK_ASSERT(count != 0U); // API contract: number of parties cannot be 0
    }

    STK_VIRT_DTOR ~Barrier()
    {}

    bool Wait() { return (WaitEx() == BARRIER_LAST_ARRIVAL); }

    EResult WaitEx();

    uint32_t GetThreshold() const { return m_threshold; }
 
private:
    STK_NONCOPYABLE_CLASS(Barrier);
 
    Mutex             m_mutex;      
    ConditionVariable m_cond;       
    const uint32_t    m_threshold;  
    uint32_t          m_count;      
    uint32_t          m_generation; 
};
 
// ---------------------------------------------------------------------------
// WaitEx
// ---------------------------------------------------------------------------
 
inline Barrier::EResult Barrier::WaitEx()
{
    EResult result = BARRIER_RELEASED;
 
    STK_ASSERT(!hw::IsInsideISR()); // API contract: caller must not be in ISR
 
    m_mutex.Lock();
 
    const uint32_t gen = m_generation;
 
    if (--m_count == 0U)
    {
        // last task to arrive: start a new generation and release everyone else
        ++m_generation;
        m_count = m_threshold;
 
        m_cond.NotifyAll();
 
        result = BARRIER_LAST_ARRIVAL;
    }
    else
    {
        // wait in a loop to guard against spurious wakeups: keep waiting while
        // we are still in the same generation we entered with
        while (gen == m_generation)
        {
            if (m_cond.WaitEx(m_mutex, WAIT_INFINITE) == WAIT_RESULT_CANCELED)
            {
                // the cancel wakes this task before m_mutex is re-acquired, so the barrier may have
                // tripped in between (the trip has then already consumed our arrival and reset
                // m_count): signal wins, report a normal release and leave the count alone
                if (gen == m_generation)
                {
                    // bail out before the barrier tripped: undo our own arrival so the count
                    // stays consistent for whichever tasks remain in this generation - do NOT
                    // let the barrier trip short-handed on our behalf
                    ++m_count;
                    result = BARRIER_CANCELED;
                }
 
                break;
            }
            // else: WAIT_RESULT_SIGNAL - NotifyAll() always pairs with ++m_generation, so a
            // genuine signal here means gen != m_generation already and the loop exits next check
        }
    }
 
    m_mutex.Unlock();
 
    return result;
}
 
} // namespace sync
} // namespace stk
 
#endif /* STK_SYNC_BARRIER_H_ */