stk::sync::RWMutex Class Reference

Reader-Writer Lock synchronization primitive for non-recursive shared and exclusive access. More...

#include <stk_sync_rwmutex.h>

Inheritance diagram for stk::sync::RWMutex:

Collaboration diagram for stk::sync::RWMutex:

Classes
class	ScopedTimedLock
	RAII wrapper for attempting exclusive write access with a timeout. More...
class	ScopedTimedReadMutex
	RAII wrapper for attempting shared read access with a timeout. More...

Public Member Functions
	RWMutex ()
	Construct an RWMutex in the unlocked state with no active readers or writers.
	~RWMutex ()
	Destructor.
EWaitResult	TimedReadLockEx (Timeout timeout_ticks)
	Acquire the lock for shared reading with a timeout, preserving the full wait outcome.
bool	TimedReadLock (Timeout timeout_ticks)
	Acquire the lock for shared reading with a timeout.
void	ReadLock ()
	Acquire the lock for shared reading.
bool	TryReadLock ()
	Attempt to acquire the lock for shared reading without blocking.
void	ReadUnlock ()
	Release the shared reader lock.
EWaitResult	TimedLockEx (Timeout timeout_ticks)
	Acquire the lock for exclusive writing with a timeout, preserving the full wait outcome.
bool	TimedLock (Timeout timeout_ticks)
	Acquire the lock for exclusive writing with a timeout.
void	Lock () override
	Acquire the lock for exclusive writing (IMutex interface).
bool	TryLock ()
	Attempt to acquire the lock for exclusive writing without blocking.
void	Unlock () override
	Release the exclusive writer lock (IMutex interface).
void	SetTraceName (const char *name)
	Set name.
const char *	GetTraceName () const
	Get name.

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

Private Attributes
ConditionVariable	m_cv_readers
	signaled when readers can proceed
ConditionVariable	m_cv_writers
	signaled when a writer can proceed
uint16_t	m_readers
	current active reader count
uint16_t	m_writers_waiting
	count of writers waiting for access
bool	m_writer_active
	true if a writer currently holds the lock

Static Private Attributes
static const uint16_t	READERS_MAX = 0xFFFEU
	maximum number of concurrent readers
static const uint16_t	WRITERS_MAX = 0xFFFEU
	maximum number of waiting writers

Detailed Description

Reader-Writer Lock synchronization primitive for non-recursive shared and exclusive access.

RWMutex allows multiple tasks to read a shared resource simultaneously (shared access) while ensuring that only one task can write to the resource at a time (exclusive access). This is particularly efficient for data structures that are read frequently but modified infrequently.

Note

Writer Preference Policy: To prevent "writer starvation," this implementation prioritizes waiting writers. If a writer is waiting for the lock, new readers will be blocked until the writer has completed its operation.

Maximum number of concurrent readers must not exceed READERS_MAX (0xFFFE). Maximum number of waiting writers must not exceed WRITERS_MAX (0xFFFE).

Non-recursive: a task must not call ReadLock() or Lock() more than once without a matching unlock. Doing so will deadlock.

// Example: Protecting app settings
stk::sync::RWMutex g_SettingsLock;
Settings           g_Settings;
 
void Engine_Task() {
    // Multiple engine instances can read settings concurrently
    stk::sync::RWMutex::ScopedTimedReadMutex guard(g_SettingsLock);
    Apply(g_Settings);
}
 
void UI_Control_Task() {
    // Exclusive access to update settings
    g_SettingsLock.Lock();
    g_Settings.volume = new_volume;
    g_SettingsLock.Unlock();
}

See also

Mutex, ConditionVariable, ScopedReadMutex

Examples

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

Definition at line 61 of file stk_sync_rwmutex.h.

Constructor & Destructor Documentation

RWMutex() [1/2]

stk::sync::RWMutex::RWMutex ( )

inlineexplicit

Construct an RWMutex in the unlocked state with no active readers or writers.

Definition at line 66 of file stk_sync_rwmutex.h.

                       : m_readers(0U), m_writers_waiting(0U), m_writer_active(false)
    {}

References m_readers, m_writer_active, and m_writers_waiting.

Referenced by operator=(), stk::sync::RWMutex::ScopedTimedLock::ScopedTimedLock(), and stk::sync::RWMutex::ScopedTimedReadMutex::ScopedTimedReadMutex().

Here is the caller graph for this function:

~RWMutex()

stk::sync::RWMutex::~RWMutex ( )

inline

Destructor.

Note

Destroying an RWMutex while readers are active, writers are waiting, or a writer holds the lock is a logical error (dangling state). An assertion is triggered in debug builds.

MISRA deviation: [STK-DEV-005] Rule 10-3-2.

Definition at line 75 of file stk_sync_rwmutex.h.

    {
        // API contract: must not be destroyed while readers are active, writers are waiting,
        // or a writer holds the lock
        STK_ASSERT((m_readers == 0U) && (m_writers_waiting == 0U) && !m_writer_active);
    }

References m_readers, m_writer_active, m_writers_waiting, STK_ASSERT, and STK_VIRT_DTOR.

RWMutex() [2/2]

stk::sync::RWMutex::RWMutex ( const RWMutex & )

privatedelete

Member Function Documentation

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 582 of file stk_common.h.

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

Lock()

void stk::sync::RWMutex::Lock ( )

inlineoverridevirtual

Acquire the lock for exclusive writing (IMutex interface).

Blocks the calling task until all active readers have released their locks and no other writer is active.

Note

Non-recursive.

Not cancelable: a void Lock() cannot report failure and must return with the lock held, so a cancellation (IKernel::CancelTaskWait()) is absorbed and the wait is retried. This also keeps the mutex re-acquisition at the end of ConditionVariable::Wait() reliable (the kernel re-locks via this method). Use TimedLockEx() if cancellation must be observed. Panics (KERNEL_PANIC_ASSERT) on any other failure.

Warning

ISR-unsafe.

Implements stk::IMutex.

Definition at line 430 of file stk_sync_rwmutex.h.

{
    EWaitResult result;
 
    do
    {
        result = TimedLockEx(WAIT_INFINITE);
    }
    while (result == WAIT_RESULT_CANCELED);
 
    if (result != WAIT_RESULT_SIGNAL)
    {
        STK_KERNEL_PANIC(KERNEL_PANIC_ASSERT);
    }
}

References stk::KERNEL_PANIC_ASSERT, stk::STK_KERNEL_PANIC(), TimedLockEx(), stk::WAIT_INFINITE, stk::WAIT_RESULT_CANCELED, and stk::WAIT_RESULT_SIGNAL.

Referenced by pthread_rwlock_wrlock(), and stk_rwmutex_lock().

Here is the call graph for this function:

Here is the caller graph for this function:

operator=()

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

privatedelete

References RWMutex().

Here is the call graph for this function:

ReadLock()

void stk::sync::RWMutex::ReadLock ( )

inline

Acquire the lock for shared reading.

Blocks the calling task if a writer is currently active or if there are writers waiting to acquire the lock.

Note

Non-recursive.

Not cancelable: a void ReadLock() cannot report failure and must return with the lock held, so a cancellation (IKernel::CancelTaskWait()) is absorbed and the wait is retried. Use TimedReadLockEx() if cancellation must be observed. Panics (KERNEL_PANIC_ASSERT) on any other failure.

Warning

ISR-unsafe.

Definition at line 309 of file stk_sync_rwmutex.h.

{
    EWaitResult result;
 
    do
    {
        result = TimedReadLockEx(WAIT_INFINITE);
    }
    while (result == WAIT_RESULT_CANCELED);
 
    if (result != WAIT_RESULT_SIGNAL)
    {
        STK_KERNEL_PANIC(KERNEL_PANIC_ASSERT);
    }
}

References stk::KERNEL_PANIC_ASSERT, stk::STK_KERNEL_PANIC(), TimedReadLockEx(), stk::WAIT_INFINITE, stk::WAIT_RESULT_CANCELED, and stk::WAIT_RESULT_SIGNAL.

Referenced by pthread_rwlock_rdlock(), and stk_rwmutex_read_lock().

Here is the call graph for this function:

Here is the caller graph for this function:

ReadUnlock()

void stk::sync::RWMutex::ReadUnlock ( )

inline

Release the shared reader lock.

Decrements the reader count. If this was the last active reader, notifies any waiting writers.

Warning

ISR-safe.

Definition at line 329 of file stk_sync_rwmutex.h.

{
    const ScopedCriticalSection cs_;
 
    STK_ASSERT(m_readers != 0U); // API contract: must have a matching ReadLock()
 
    m_readers = static_cast<uint16_t>(m_readers - 1U);
 
    // wake a waiting writer when the last reader exits
    if (m_readers == 0U)
    {
        m_cv_writers.NotifyOne_CS();
    }
}

References m_cv_writers, m_readers, and STK_ASSERT.

Referenced by stk_rwmutex_read_unlock().

Here is the caller graph for this function:

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 570 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(), stk::memory::BlockMemoryPool::BlockMemoryPool(), stk::memory::BytePool::BytePool(), stk::memory::BytePool::BytePool(), tx_block_pool_create(), tx_event_flags_create(), tx_mutex_create(), tx_queue_create(), and tx_semaphore_create().

Here is the caller graph for this function:

TimedLock()

bool stk::sync::RWMutex::TimedLock ( Timeout timeout_ticks )

inline

Acquire the lock for exclusive writing with a timeout.

Parameters

[in]

timeout_ticks

Maximum time to wait (ticks).

Returns

True if lock acquired, false otherwise (timeout, cancellation or NO_WAIT on a busy lock). Use TimedLockEx() to tell these apart.

Note

Non-recursive.

Warning

ISR-safe only with timeout_ticks = NO_WAIT, ISR-unsafe otherwise.

Definition at line 212 of file stk_sync_rwmutex.h.

{ return (TimedLockEx(timeout_ticks) == WAIT_RESULT_SIGNAL); }

References TimedLockEx(), and stk::WAIT_RESULT_SIGNAL.

Referenced by stk_rwmutex_timed_lock(), and TryLock().

Here is the call graph for this function:

Here is the caller graph for this function:

TimedLockEx()

EWaitResult stk::sync::RWMutex::TimedLockEx ( Timeout timeout_ticks )

inline

Acquire the lock for exclusive writing with a timeout, preserving the full wait outcome.

Parameters

[in]

timeout_ticks

Maximum time to wait (ticks).

Returns

WAIT_RESULT_SIGNAL if the lock was acquired (here "signal" means "lock acquired": the predicate is re-checked after every wake), WAIT_RESULT_TIMEOUT if the timeout expired (or NO_WAIT was passed and the lock was busy), WAIT_RESULT_CANCELED if the wait was cancelled via IKernel::CancelTaskWait(), WAIT_RESULT_FAIL if the kernel rejected the wait.

Note

Non-recursive.

Warning

ISR-safe only with timeout_ticks = NO_WAIT, ISR-unsafe otherwise.

Definition at line 348 of file stk_sync_rwmutex.h.

{
    EWaitResult result = WAIT_RESULT_SIGNAL;
    ScopedCriticalSection cs_;
 
    STK_ASSERT(m_writers_waiting < WRITERS_MAX); // API contract: waiting writer count must not exceed maximum
 
    m_writers_waiting = static_cast<uint16_t>(m_writers_waiting + 1U);
 
    const bool timed_wait = (timeout_ticks != WAIT_INFINITE) && (timeout_ticks != NO_WAIT);
 
    // capture an absolute deadline once, before entering the wait loop,
    // this prevents the timeout from being silently restarted on each
    // spurious wakeup; kept as 64-bit Ticks (not truncated to 32-bit Timeout) so that
    // the deadline and the current time stay comparable across the 32-bit tick wraparound
    const Ticks deadline = (timed_wait ?
        (GetTicks() + timeout_ticks) : static_cast<Ticks>(0));
 
    // wait until there are no active readers and no active writer
    while (m_writer_active || (m_readers != 0U))
    {
        Timeout remaining = timeout_ticks;
        if (timed_wait)
        {
            // left <= timeout_ticks < WAIT_INFINITE, so the narrowing cast is lossless
            const Ticks left = (deadline - GetTicks());
            remaining = ((left > 0) ? static_cast<Timeout>(left) : NO_WAIT);
        }
 
        result = m_cv_writers.WaitEx(cs_, remaining);
        if (result != WAIT_RESULT_SIGNAL)
        {
            // timeout, cancellation or kernel failure: withdraw from the waiting writers queue
            m_writers_waiting = static_cast<uint16_t>(m_writers_waiting - 1U);
 
            // readers may have been blocked only by this writer's preference: with no writer left
            // and none active, let them re-evaluate (otherwise they sleep until their own timeout,
            // or forever with WAIT_INFINITE)
            if (!m_writer_active)
            {
                if (m_writers_waiting == 0U)
                {
                    m_cv_readers.NotifyAll_CS();
                }
                // the withdrawing writer may have consumed a NotifyOne() meant for the next writer:
                // if the lock is free, pass the wake on (a spurious wake is harmless, the predicate
                // is re-checked by the woken writer)
                else if (m_readers == 0U)
                {
                    m_cv_writers.NotifyOne_CS();
                }
                else
                {
                    // readers still active, the last ReadUnlock() will wake the next writer
                }
            }
 
            break;
        }
    }
 
    // only finalize state if the wait didn't time out
    if (result == WAIT_RESULT_SIGNAL)
    {
        m_writers_waiting = static_cast<uint16_t>(m_writers_waiting - 1U);
 
        // kernel invariant: no readers and no active writer when lock is granted
        if ((m_readers != 0U) || m_writer_active)
        {
            STK_KERNEL_PANIC(KERNEL_PANIC_ASSERT);
        }
 
        m_writer_active = true;
    }
 
    return result;
}

References stk::GetTicks(), stk::KERNEL_PANIC_ASSERT, m_cv_readers, m_cv_writers, m_readers, m_writer_active, m_writers_waiting, stk::NO_WAIT, STK_ASSERT, stk::STK_KERNEL_PANIC(), stk::WAIT_INFINITE, stk::WAIT_RESULT_SIGNAL, and WRITERS_MAX.

Referenced by Lock(), pthread_rwlock_timedwrlock(), stk::sync::RWMutex::ScopedTimedLock::ScopedTimedLock(), stk_rwmutex_timed_lock_ex(), and TimedLock().

Here is the call graph for this function:

Here is the caller graph for this function:

TimedReadLock()

bool stk::sync::RWMutex::TimedReadLock ( Timeout timeout_ticks )

inline

Acquire the lock for shared reading with a timeout.

Parameters

[in]

timeout_ticks

Maximum time to wait (ticks).

Note

Non-recursive.

Returns

True if lock acquired, false otherwise (timeout, cancellation or NO_WAIT on a busy lock). Use TimedReadLockEx() to tell these apart.

Warning

ISR-safe only with timeout_ticks = NO_WAIT, ISR-unsafe otherwise.

Definition at line 163 of file stk_sync_rwmutex.h.

{ return (TimedReadLockEx(timeout_ticks) == WAIT_RESULT_SIGNAL); }

References TimedReadLockEx(), and stk::WAIT_RESULT_SIGNAL.

Referenced by stk_rwmutex_timed_read_lock(), and TryReadLock().

Here is the call graph for this function:

Here is the caller graph for this function:

TimedReadLockEx()

EWaitResult stk::sync::RWMutex::TimedReadLockEx ( Timeout timeout_ticks )

inline

Acquire the lock for shared reading with a timeout, preserving the full wait outcome.

Parameters

[in]

timeout_ticks

Maximum time to wait (ticks).

Note

Non-recursive.

Returns

WAIT_RESULT_SIGNAL if the lock was acquired (here "signal" means "lock acquired": the predicate is re-checked after every wake), WAIT_RESULT_TIMEOUT if the timeout expired (or NO_WAIT was passed and the lock was busy), WAIT_RESULT_CANCELED if the wait was cancelled via IKernel::CancelTaskWait(), WAIT_RESULT_FAIL if the kernel rejected the wait.

Warning

ISR-safe only with timeout_ticks = NO_WAIT, ISR-unsafe otherwise.

Definition at line 260 of file stk_sync_rwmutex.h.

{
    EWaitResult result = WAIT_RESULT_SIGNAL;
    ScopedCriticalSection cs_;
 
    const bool timed_wait = (timeout_ticks != WAIT_INFINITE) && (timeout_ticks != NO_WAIT);
 
    // capture an absolute deadline once, before entering the wait loop,
    // this prevents the timeout from being silently restarted on each
    // spurious wakeup; kept as 64-bit Ticks (not truncated to 32-bit Timeout) so that
    // the deadline and the current time stay comparable across the 32-bit tick wraparound
    const Ticks deadline = (timed_wait ?
        (GetTicks() + timeout_ticks) : static_cast<Ticks>(0));
 
    // wait if there is an active writer or if writers are waiting (Writer Preference)
    while (m_writer_active || (m_writers_waiting != 0U))
    {
        Timeout remaining = timeout_ticks;
        if (timed_wait)
        {
            // left <= timeout_ticks < WAIT_INFINITE, so the narrowing cast is lossless
            const Ticks left = (deadline - GetTicks());
            remaining = ((left > 0) ? static_cast<Timeout>(left) : NO_WAIT);
        }
 
        result = m_cv_readers.WaitEx(cs_, remaining);
        if (result != WAIT_RESULT_SIGNAL)
        {
            break; // timeout, cancellation or kernel failure: propagate to the caller
        }
 
        // re-check on wake: another writer may have queued up while this task was sleeping
    }
 
    // only increment reader count if the lock was successfully acquired
    if (result == WAIT_RESULT_SIGNAL)
    {
        STK_ASSERT(m_readers < READERS_MAX); // API contract: reader count must not exceed maximum
 
        m_readers = static_cast<uint16_t>(m_readers + 1U);
    }
 
    return result;
}

References stk::GetTicks(), m_cv_readers, m_readers, m_writer_active, m_writers_waiting, stk::NO_WAIT, READERS_MAX, STK_ASSERT, stk::WAIT_INFINITE, and stk::WAIT_RESULT_SIGNAL.

Referenced by pthread_rwlock_timedrdlock(), ReadLock(), stk::sync::RWMutex::ScopedTimedReadMutex::ScopedTimedReadMutex(), stk_rwmutex_timed_read_lock_ex(), and TimedReadLock().

Here is the call graph for this function:

Here is the caller graph for this function:

TryLock()

bool stk::sync::RWMutex::TryLock ( )

inline

Attempt to acquire the lock for exclusive writing without blocking.

Checks if any readers are active or if another writer is active.

Note

Non-recursive.

Returns

True if the exclusive lock was acquired, false otherwise.

Warning

ISR-safe.

Definition at line 234 of file stk_sync_rwmutex.h.

{ return TimedLock(NO_WAIT); }

References stk::NO_WAIT, and TimedLock().

Referenced by stk_rwmutex_trylock().

Here is the call graph for this function:

Here is the caller graph for this function:

TryReadLock()

bool stk::sync::RWMutex::TryReadLock ( )

inline

Attempt to acquire the lock for shared reading without blocking.

Checks if a writer is active or waiting. If the resource is available for reading, it increments the reader count and returns immediately.

Note

Non-recursive.

Returns

True if the read lock was acquired, false if a writer is active or waiting.

Warning

ISR-safe.

Definition at line 184 of file stk_sync_rwmutex.h.

{ return TimedReadLock(NO_WAIT); }

References stk::NO_WAIT, and TimedReadLock().

Referenced by pthread_rwlock_tryrdlock(), and stk_rwmutex_try_read_lock().

Here is the call graph for this function:

Here is the caller graph for this function:

Unlock()

void stk::sync::RWMutex::Unlock ( )

inlineoverridevirtual

Release the exclusive writer lock (IMutex interface).

Releases the lock and prioritizes waking waiting writers. If no writers are waiting, wakes all waiting readers.

Warning

ISR-safe.

Implements stk::IMutex.

Definition at line 450 of file stk_sync_rwmutex.h.

{
    const ScopedCriticalSection cs_;
 
    STK_ASSERT(m_writer_active); // API contract: caller must hold the write lock
 
    m_writer_active = false;
 
    // prioritize waking waiting writers to prevent writer starvation;
    // only wake readers if no writers are queued
    if (m_writers_waiting != 0U)
    {
        m_cv_writers.NotifyOne_CS();
    }
    else
    {
        m_cv_readers.NotifyAll_CS();
    }
}

References m_cv_readers, m_cv_writers, m_writer_active, m_writers_waiting, and STK_ASSERT.

Referenced by stk_rwmutex_unlock().

Here is the caller graph for this function:

Member Data Documentation

m_cv_readers

ConditionVariable stk::sync::RWMutex::m_cv_readers

private

signaled when readers can proceed

Definition at line 249 of file stk_sync_rwmutex.h.

Referenced by TimedLockEx(), TimedReadLockEx(), and Unlock().

m_cv_writers

ConditionVariable stk::sync::RWMutex::m_cv_writers

private

signaled when a writer can proceed

Definition at line 250 of file stk_sync_rwmutex.h.

Referenced by ReadUnlock(), TimedLockEx(), and Unlock().

m_readers

uint16_t stk::sync::RWMutex::m_readers

private

current active reader count

Definition at line 251 of file stk_sync_rwmutex.h.

Referenced by ReadUnlock(), RWMutex(), TimedLockEx(), TimedReadLockEx(), and ~RWMutex().

m_writer_active

bool stk::sync::RWMutex::m_writer_active

private

true if a writer currently holds the lock

Definition at line 253 of file stk_sync_rwmutex.h.

Referenced by RWMutex(), TimedLockEx(), TimedReadLockEx(), Unlock(), and ~RWMutex().

m_writers_waiting

uint16_t stk::sync::RWMutex::m_writers_waiting

private

count of writers waiting for access

Definition at line 252 of file stk_sync_rwmutex.h.

Referenced by RWMutex(), TimedLockEx(), TimedReadLockEx(), Unlock(), and ~RWMutex().

READERS_MAX

const uint16_t stk::sync::RWMutex::READERS_MAX = 0xFFFEU

staticprivate

maximum number of concurrent readers

Definition at line 246 of file stk_sync_rwmutex.h.

Referenced by TimedReadLockEx().

WRITERS_MAX

const uint16_t stk::sync::RWMutex::WRITERS_MAX = 0xFFFEU

staticprivate

maximum number of waiting writers

Definition at line 247 of file stk_sync_rwmutex.h.

Referenced by TimedLockEx().

---

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

• stk_sync_rwmutex.h