stk::sync::Barrier Class Reference

Cyclic barrier that blocks a fixed-size group of tasks until all of them have arrived. More...

#include <stk_sync_barrier.h>

Inheritance diagram for stk::sync::Barrier:

Collaboration diagram for stk::sync::Barrier:

Public Member Functions
	Barrier (uint32_t count)
	Constructor.
	~Barrier ()
	Destructor.
bool	Wait ()
	Block the calling task until count tasks have called Wait().
uint32_t	GetThreshold () const
	Get the number of tasks required to trip the barrier.
void	SetTraceName (const char *name)
	Set name.
const char *	GetTraceName () const
	Get name.

Private Member Functions
	Barrier (const Barrier &)=delete
Barrier &	operator= (const Barrier &)=delete

Private Attributes
Mutex	m_mutex
	protects m_count / m_generation and serializes calls to m_cond
ConditionVariable	m_cond
	signals waiting tasks when the current generation completes
const uint32_t	m_threshold
	number of tasks required to trip the barrier
uint32_t	m_count
	number of tasks still to arrive in the current generation
uint32_t	m_generation
	generation counter, incremented every time the barrier trips

Detailed Description

Cyclic barrier that blocks a fixed-size group of tasks until all of them have arrived.

A Barrier lets a set of count tasks rendezvous at a common point: each task calls Wait() and blocks until the last member of the group also calls Wait(). Once the last task arrives, all waiting tasks are released simultaneously and the barrier automatically resets (cyclic behavior), ready to be reused for the next round.

Note

Implemented on top of Mutex and ConditionVariable. A generation counter is used to distinguish successive rounds and to guard the wait loop against spurious wakeups.

// Example: synchronizing 3 worker tasks at the end of each processing round
stk::sync::Barrier g_Barrier(3U);
 
void Task_Worker() {
    for (;;) {
        // ... do per-round work ...
 
        // block here until all 3 tasks reach this point
        if (g_Barrier.Wait()) {
            // only the last task to arrive executes this branch:
            // safe to do once-per-round bookkeeping here
        }
    }
}

Note

Only available when kernel is compiled with KERNEL_SYNC mode enabled.

See also

Mutex, ConditionVariable

Examples

D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 54 of file stk_sync_barrier.h.

Constructor & Destructor Documentation

Barrier() [1/2]

stk::sync::Barrier::Barrier ( uint32_t count )

inlineexplicit

Constructor.

Parameters

[in]

count

Number of tasks that must call Wait() before any of them is released.

Note

count must not be 0.

Definition at line 61 of file stk_sync_barrier.h.

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

References m_count, m_generation, m_threshold, and STK_ASSERT.

Referenced by Barrier().

Here is the caller graph for this function:

~Barrier()

stk::sync::Barrier::~Barrier ( )

inline

Destructor.

Definition at line 68 of file stk_sync_barrier.h.

    {}

References STK_VIRT_DTOR.

Barrier() [2/2]

stk::sync::Barrier::Barrier ( const Barrier & )

privatedelete

References Barrier().

Here is the call graph for this function:

Member Function Documentation

GetThreshold()

uint32_t stk::sync::Barrier::GetThreshold ( ) const

inline

Get the number of tasks required to trip the barrier.

Warning

ISR-safe.

Definition at line 83 of file stk_sync_barrier.h.

{ return m_threshold; }

References m_threshold.

Referenced by stk_barrier_get_threshold().

Here is the caller graph for this function:

GetTraceName()

const char * stk::ITraceable::GetTraceName ( ) const

inlineinherited

Get name.

Returns

Name string, or NULL if not set or if STK_SYNC_DEBUG_NAMES is 0.

Definition at line 534 of file stk_common.h.

    {
    #if STK_SYNC_DEBUG_NAMES
        return m_trace_name;
    #else
        return nullptr;
    #endif
    }

operator=()

Barrier & stk::sync::Barrier::operator= ( const Barrier & )

privatedelete

SetTraceName()

void stk::ITraceable::SetTraceName ( const char * name )

inlineinherited

Set name.

Parameters

[in]

name

Null-terminated string or NULL.

Note

If STK_SYNC_DEBUG_NAMES is 0 then calling this function has no effect.

Definition at line 522 of file stk_common.h.

    {
    #if STK_SYNC_DEBUG_NAMES
        m_trace_name = name;
    #else
        STK_UNUSED(name);
    #endif
    }

References STK_UNUSED.

Referenced by stk::memory::BlockMemoryPool::BlockMemoryPool(), and stk::memory::BlockMemoryPool::BlockMemoryPool().

Here is the caller graph for this function:

Wait()

bool stk::sync::Barrier::Wait ( )

inline

Block the calling task until count tasks have called Wait().

Once the last task arrives, all currently waiting tasks are woken up and the barrier resets itself so it can be reused for the next round.

Warning

ISR-unsafe.

Returns

True if the calling task was the last one to arrive (and thus released the others), false if the calling task was one of the released waiters.

Definition at line 99 of file stk_sync_barrier.h.

{
    bool is_last = false;
 
    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();
 
        is_last = true;
    }
    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)
        {
            STK_UNUSED(m_cond.Wait(m_mutex, WAIT_INFINITE));
        }
    }
 
    m_mutex.Unlock();
 
    return is_last;
}

References stk::hw::IsInsideISR(), m_cond, m_count, m_generation, m_mutex, m_threshold, STK_ASSERT, STK_UNUSED, and stk::WAIT_INFINITE.

Referenced by stk_barrier_wait().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

m_cond

ConditionVariable stk::sync::Barrier::m_cond

private

signals waiting tasks when the current generation completes

Definition at line 89 of file stk_sync_barrier.h.

Referenced by Wait().

m_count

uint32_t stk::sync::Barrier::m_count

private

number of tasks still to arrive in the current generation

Definition at line 91 of file stk_sync_barrier.h.

Referenced by Barrier(), and Wait().

m_generation

uint32_t stk::sync::Barrier::m_generation

private

generation counter, incremented every time the barrier trips

Definition at line 92 of file stk_sync_barrier.h.

Referenced by Barrier(), and Wait().

m_mutex

Mutex stk::sync::Barrier::m_mutex

private

protects m_count / m_generation and serializes calls to m_cond

Definition at line 88 of file stk_sync_barrier.h.

Referenced by Wait().

m_threshold

const uint32_t stk::sync::Barrier::m_threshold

private

number of tasks required to trip the barrier

Definition at line 90 of file stk_sync_barrier.h.

Referenced by Barrier(), GetThreshold(), and Wait().

---

The documentation for this class was generated from the following file:

• stk_sync_barrier.h