stk_sync_cv.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_CV_H_
#define STK_SYNC_CV_H_
 
#include "stk_sync_cs.h"

 
namespace stk {
namespace sync {

class ConditionVariable final : private SyncObjectBase, public ITraceable
{
public:
    explicit ConditionVariable()
    {}

    STK_VIRT_DTOR  ~ConditionVariable()
    {
        STK_ASSERT(m_wait_list.IsEmpty()); // API contract: must not be destroyed with waiting tasks
    }

    bool Wait(IMutex &mutex, Timeout timeout_ticks = WAIT_INFINITE);

    EWaitResult WaitEx(IMutex &mutex, Timeout timeout_ticks = WAIT_INFINITE);

    void NotifyOne();

    void NotifyOne_CS();

    void NotifyAll();

    void NotifyAll_CS();
 
private:
    STK_NONCOPYABLE_CLASS(ConditionVariable);
};
 
// ---------------------------------------------------------------------------
// Wait
// ---------------------------------------------------------------------------
 
inline bool ConditionVariable::Wait(IMutex &mutex, Timeout timeout_ticks)
{
    return (WaitEx(mutex, timeout_ticks) == WAIT_RESULT_SIGNAL);
}
 
// ---------------------------------------------------------------------------
// WaitEx
// ---------------------------------------------------------------------------
 
inline EWaitResult ConditionVariable::WaitEx(IMutex &mutex, Timeout timeout_ticks)
{
    // API contract: mutex must be locked by the calling task before Wait() is called.
    // The kernel releases it atomically during suspension and re-acquires it on wake.
 
    // NO_WAIT never touches the kernel wait path: treat it the same as an
    // immediately-expired timeout (consistent with the pre-existing bool Wait() semantics).
    EWaitResult result = WAIT_RESULT_TIMEOUT;
 
    if (timeout_ticks != NO_WAIT)
    {
        STK_ASSERT(!hw::IsInsideISR()); // API contract: caller must not be in ISR if timeout_ticks!=NO_WAIT
 
        result = IKernelService::GetInstance()->Wait(this, &mutex, timeout_ticks);
    }
 
    return result;
}
 
// ---------------------------------------------------------------------------
// NotifyOne
// ---------------------------------------------------------------------------
 
inline void ConditionVariable::NotifyOne()
{
    const ScopedCriticalSection cs_;
    NotifyOne_CS();
}
 
// ---------------------------------------------------------------------------
// NotifyOne_CS
// ---------------------------------------------------------------------------
 
inline void ConditionVariable::NotifyOne_CS()
{
    WakeOne(); // wakes the first task in the wait list (FIFO order), if any
}
 
// ---------------------------------------------------------------------------
// NotifyAll
// ---------------------------------------------------------------------------
 
inline void ConditionVariable::NotifyAll()
{
    const ScopedCriticalSection cs_;
    NotifyAll_CS(); // wakes all tasks in the wait list simultaneously
}
 
// ---------------------------------------------------------------------------
// NotifyAll_CS
// ---------------------------------------------------------------------------
 
inline void ConditionVariable::NotifyAll_CS()
{
    WakeAll(); // wakes all tasks in the wait list simultaneously
}
 
} // namespace sync
} // namespace stk
 
#endif /* STK_SYNC_CV_H_ */