|
SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
|
Recursive mutex primitive that allows the same thread to acquire the lock multiple times. More...
#include <stk_sync_mutex.h>
Public Types | |
| typedef DLHeadType | ListHeadType |
| List head type for ISyncObject elements. | |
| typedef DLEntryType | ListEntryType |
| List entry type of ISyncObject elements. | |
| enum | |
| A tag for type-safe casts done by CastListEntryToParent. More... | |
| typedef DListEntry< ISyncObject, TClosedLoop > | DLEntryType |
| Convenience alias for this entry type. Used to avoid repeating the full template spelling. | |
| typedef DListHead< ISyncObject, TClosedLoop > | DLHeadType |
| Convenience alias for the corresponding list head type. | |
Public Member Functions | |
| Mutex () | |
| Constructor. | |
| ~Mutex () | |
| Destructor. | |
| EWaitResult | TimedLockEx (Timeout timeout_ticks) |
| Acquire lock, preserving the full wait outcome. | |
| bool | TimedLock (Timeout timeout_ticks) |
| Acquire lock. | |
| void | Lock () override |
| Acquire lock. | |
| bool | TryLock () |
| Try to acquire the lock without blocking. | |
| void | Unlock () override |
| Release lock. | |
| TId | GetOwner () const |
| Get owner of the mutex. | |
| bool | IsLocked () const |
| Check if the mutex is currently locked. | |
| uint16_t | GetRecursionCount () const |
| Get current recursion depth. | |
| void | AddWaitObject (IWaitObject *wobj) override |
| Called by kernel when a new task starts waiting on this event. | |
| void | RemoveWaitObject (IWaitObject *wobj) override |
| Called by kernel when a waiting task is being removed (timeout expired, wait aborted, task terminated etc.). | |
| const IWaitObject::ListHeadType & | GetWaitList () const override |
| Get list of tasks blocked on this object. | |
| virtual bool | Tick (Timeout elapsed_ticks) |
| Called by kernel on every system tick to handle timeout logic of waiting tasks. | |
| Weight | FindWeightHigherThan (Weight comp) const |
| Find higher weight within linked wait objects. | |
| TId | GetFirstWaiterTid () const |
| Get id of the task which is first in the wait list (FIFO order), i.e. the one that WakeOne() would wake next. | |
| DLHeadType * | GetHead () |
| Get the list head this entry currently belongs to. | |
| DLEntryType * | GetNext () |
| Get the next entry in the list. | |
| DLEntryType * | GetPrev () |
| Get the previous entry in the list. | |
| bool | IsLinked () const |
| Check whether this entry is currently a member of any list. | |
| operator ISyncObject * () | |
| Implicit conversion to a mutable pointer to the host object (T). | |
| operator const ISyncObject * () const | |
| Implicit conversion to a const pointer to the host object (T). | |
| void | SetTraceName (const char *name) |
| Set name. | |
| const char * | GetTraceName () const |
| Get name. | |
Static Public Member Functions | |
| static void | AddWaitObject (IWaitObject::ListHeadType &wlist, IWaitObject *wobj) |
| Called by kernel when a new task starts waiting on this event. | |
| static void | RemoveWaitObject (IWaitObject::ListHeadType &wlist, IWaitObject *wobj) |
| Called by kernel when a waiting task is being removed (timeout expired, wait aborted, task terminated etc.). | |
| static void | WakeOne (IWaitObject::ListHeadType &wlist) |
| Wake the first task in the wait list (FIFO order). | |
| static void | WakeAll (IWaitObject::ListHeadType &wlist) |
| Wake all tasks currently in the wait list. | |
Static Public Attributes | |
| static const uint16_t | RECURSION_MAX = 0xFFFEU |
| maximum nesting depth | |
Protected Member Functions | |
| void | WakeOne () override |
| Wake the first task in the wait list (FIFO order). | |
| void | WakeAll () override |
| Wake all tasks currently in the wait list. | |
| IWaitObject::ListHeadType & | GetMutableWaitList () override |
| Get list of tasks blocked on this object. | |
Protected Attributes | |
| IWaitObject::ListHeadType | m_wait_list |
| Tasks blocked on this object. | |
Private Member Functions | |
| Mutex (const Mutex &)=delete | |
| Mutex & | operator= (const Mutex &)=delete |
| void | Link (DLHeadType *head, DLEntryType *next, DLEntryType *prev) |
| Wire this entry into a list between prev and next. | |
| void | Unlink () |
| Remove this entry from its current list. | |
Private Attributes | |
| TId | m_owner_tid |
| thread id of the current owner | |
| uint16_t | m_recursion_count |
| recursion depth | |
| DLHeadType * | m_head |
Owning list head, or NULL when the entry is not linked. | |
| DLEntryType * | m_next |
Next entry in the list, or NULL (open list boundary) / first entry (closed loop). | |
| DLEntryType * | m_prev |
Previous entry in the list, or NULL (open list boundary) / last entry (closed loop). | |
Recursive mutex primitive that allows the same thread to acquire the lock multiple times.
Recursive mutex tracks ownership and a recursion count. If the owning thread calls Lock() again, the count is incremented and the call returns immediately without blocking. The lock is only fully released when Unlock() has been called an equal number of times.
Definition at line 54 of file stk_sync_mutex.h.
|
inherited |
Convenience alias for this entry type. Used to avoid repeating the full template spelling.
Definition at line 75 of file stk_linked_list.h.
|
inherited |
Convenience alias for the corresponding list head type.
Definition at line 80 of file stk_linked_list.h.
|
inherited |
List entry type of ISyncObject elements.
Definition at line 672 of file stk_common.h.
|
inherited |
List head type for ISyncObject elements.
Definition at line 667 of file stk_common.h.
|
inherited |
A tag for type-safe casts done by CastListEntryToParent.
Definition at line 70 of file stk_linked_list.h.
|
inlineexplicit |
Constructor.
Definition at line 61 of file stk_sync_mutex.h.
References m_owner_tid, m_recursion_count, and stk::TID_NONE.
Referenced by Mutex().
|
inline |
Destructor.
Definition at line 69 of file stk_sync_mutex.h.
References stk::SyncObjectBase::m_wait_list, STK_ASSERT, and STK_VIRT_DTOR.
Referenced by pthread_mutex_destroy().
|
privatedelete |
|
inlinestaticinherited |
Called by kernel when a new task starts waiting on this event.
| [in] | wlist | Wait list. |
| [in] | wobj | Wait object representing blocked task. |
Definition at line 679 of file stk_common.h.
References stk::detail::DListEntry< T, TClosedLoop >::GetHead(), stk::detail::DListHead< T, TClosedLoop >::LinkBack(), and STK_ASSERT.
Referenced by stk::SyncObjectBase::AddWaitObject(), and stk::Kernel< TMode, TSize, TStrategy, TPlatform >::KernelTask::WaitObject::SetupWait().
|
inlineoverridevirtualinherited |
Called by kernel when a new task starts waiting on this event.
| [in] | wobj | Wait object representing blocked task. |
Implements stk::ISyncObject.
Definition at line 255 of file stk_helper.h.
References stk::ISyncObject::AddWaitObject(), and m_wait_list.
Find higher weight within linked wait objects.
Implementation of ISyncObject::FindWeightHigherThan, see ISyncObject. Placed here as it depends on GetUserTaskFromTid.
| [in] | comp | Weight to compare with. |
Definition at line 349 of file stk_helper.h.
References stk::detail::DListEntry< T, TClosedLoop >::GetNext(), stk::IWaitObject::GetTid(), stk::GetUserTaskFromTid(), GetWaitList(), stk::ITask::GetWeight(), stk::detail::DListCast::ListEntryToParent(), and stk::NO_WEIGHT.
Referenced by stk::Kernel< TMode, TSize, TStrategy, TPlatform >::OnRestoreWeight(), stk::sync::FastMutex::Unlock(), and stk::sync::Mutex::Unlock().
|
inlineinherited |
Get id of the task which is first in the wait list (FIFO order), i.e. the one that WakeOne() would wake next.
Definition at line 777 of file stk_common.h.
References stk::IWaitObject::GetTid(), GetWaitList(), stk::detail::DListCast::ListEntryToParent(), and stk::TID_NONE.
|
inlineinherited |
Get the list head this entry currently belongs to.
NULL if the entry is not linked. Definition at line 85 of file stk_linked_list.h.
Referenced by stk::SyncObjectBase::~SyncObjectBase().
|
inlineoverrideprotectedvirtualinherited |
Get list of tasks blocked on this object.
Implements stk::ISyncObject.
Definition at line 306 of file stk_helper.h.
References m_wait_list.
|
inlineinherited |
Get the next entry in the list.
NULL for the last entry; in a closed loop the last entry wraps to the first one, so the result is never NULL for a linked entry. Definition at line 96 of file stk_linked_list.h.
|
inline |
Get owner of the mutex.
Definition at line 123 of file stk_sync_mutex.h.
References m_owner_tid.
Referenced by stk::pthread::IsMutexOwner(), and tx_mutex_info_get().
|
inlineinherited |
Get the previous entry in the list.
NULL for the first entry; in a closed loop the first entry wraps to the last one, so the result is never NULL for a linked entry. Definition at line 106 of file stk_linked_list.h.
|
inline |
Get current recursion depth.
Definition at line 140 of file stk_sync_mutex.h.
References m_recursion_count.
Referenced by stk::pthread::PreLockCheck(), and tx_mutex_info_get().
|
inlineinherited |
Get name.
NULL if not set or if STK_SYNC_DEBUG_NAMES is 0. Definition at line 629 of file stk_common.h.
|
inlineoverridevirtualinherited |
Get list of tasks blocked on this object.
Implements stk::ISyncObject.
Definition at line 265 of file stk_helper.h.
References m_wait_list.
|
inlineinherited |
Check whether this entry is currently a member of any list.
true if linked (m_head != NULL); false otherwise. Definition at line 115 of file stk_linked_list.h.
|
inline |
Check if the mutex is currently locked.
Definition at line 129 of file stk_sync_mutex.h.
References m_owner_tid, and stk::TID_NONE.
|
inlineprivateinherited |
Wire this entry into a list between prev and next.
| [in] | head | The owning DListHead. Stored as a back-pointer for IsLinked() and ownership checks. |
| [in] | next | The entry that will follow this one, or NULL if this becomes the last entry. |
| [in] | prev | The entry that will precede this one, or NULL if this becomes the first entry. |
Definition at line 150 of file stk_linked_list.h.
|
inlineoverridevirtual |
Acquire lock.
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. Implements stk::IMutex.
Definition at line 239 of file stk_sync_mutex.h.
References stk::KERNEL_PANIC_ASSERT, stk::STK_KERNEL_PANIC(), TimedLockEx(), stk::WAIT_INFINITE, stk::WAIT_RESULT_CANCELED, and stk::WAIT_RESULT_SIGNAL.
Referenced by MqReceiveImpl(), MqSendImpl(), pthread_mutex_lock(), pthread_once(), pthread_spin_lock(), and stk_mutex_lock().
|
inlineinherited |
Implicit conversion to a const pointer to the host object (T).
Definition at line 129 of file stk_linked_list.h.
|
inlineinherited |
Implicit conversion to a mutable pointer to the host object (T).
Definition at line 122 of file stk_linked_list.h.
|
inlinestaticinherited |
Called by kernel when a waiting task is being removed (timeout expired, wait aborted, task terminated etc.).
| [in] | wlist | Wait list. |
| [in] | wobj | Wait object to remove from the wait list. |
Definition at line 696 of file stk_common.h.
References stk::detail::DListEntry< T, TClosedLoop >::GetHead(), STK_ASSERT, and stk::detail::DListHead< T, TClosedLoop >::Unlink().
Referenced by stk::SyncObjectBase::RemoveWaitObject().
|
inlineoverridevirtualinherited |
Called by kernel when a waiting task is being removed (timeout expired, wait aborted, task terminated etc.).
| [in] | wobj | Wait object to remove from the wait list. |
Implements stk::ISyncObject.
Definition at line 260 of file stk_helper.h.
References m_wait_list, and stk::ISyncObject::RemoveWaitObject().
Referenced by stk::sync::Event::RemoveWaitObject().
|
inlineinherited |
Set name.
| [in] | name | Null-terminated string or NULL. |
Definition at line 617 of file stk_common.h.
References STK_UNUSED.
Referenced by stk::memory::BlockMemoryPool::BlockMemoryPool(), stk::memory::BlockMemoryPool::BlockMemoryPool(), stk::memory::BytePool::BytePool(), stk::memory::BytePool::BytePool(), RunExample(), tx_block_pool_create(), tx_mutex_create(), and tx_queue_create().
|
inlinevirtualinherited |
Called by kernel on every system tick to handle timeout logic of waiting tasks.
Implementation of ISyncObject::Tick, see ISyncObject. Placed here as it depends on hw namespace.
| [in] | elapsed_ticks | Number of ticks elapsed between this and previous calls, in case of KERNEL_TICKLESS mode this value can be >1, for non-tickless mode it is always 1. |
true if this synchronization object still has waiters with a finite timeout and requires further tick calls. false if the wait list is empty or all remaining waiters have infinite timeouts, signaling to the kernel that it may stop calling Tick() for this object until a new waiter is added. false, the kernel unlinks this object from its active sync list. It will be re-linked automatically when the next waiter is added via AddWaitObject(). Definition at line 315 of file stk_helper.h.
References stk::detail::DListHead< T, TClosedLoop >::GetFirst(), GetMutableWaitList(), stk::detail::DListEntry< T, TClosedLoop >::GetNext(), stk::detail::DListHead< T, TClosedLoop >::IsEmpty(), stk::detail::DListCast::ListEntryToParent(), stk::IWaitObject::Tick(), and stk::IWaitObject::Wake().
|
inline |
Acquire lock.
| [in] | timeout_ticks | Maximum time to wait (ticks). |
NO_WAIT, ISR-unsafe otherwise. TimedLockEx() to tell these apart. Definition at line 94 of file stk_sync_mutex.h.
References TimedLockEx(), and stk::WAIT_RESULT_SIGNAL.
Referenced by stk_mutex_timed_lock(), and TryLock().
|
inline |
Acquire lock, preserving the full wait outcome.
| [in] | timeout_ticks | Maximum time to wait (ticks). |
NO_WAIT, ISR-unsafe otherwise. WAIT_RESULT_SIGNAL if the lock was acquired (note: here "signal" means "lock acquired", including the immediate and recursive paths where no notification was involved), WAIT_RESULT_TIMEOUT if the lock was busy and the timeout expired (or NO_WAIT was passed), WAIT_RESULT_CANCELED if the wait was cancelled via IKernel::CancelTaskWait(), WAIT_RESULT_FAIL if the kernel rejected the wait. Definition at line 153 of file stk_sync_mutex.h.
References stk::IKernelService::GetInstance(), stk::IKernelService::GetTid(), stk::GetUserTaskFromTid(), stk::SyncObjectBase::IKernelService, stk::IKernelService::InheritWeight(), stk::hw::IsInsideISR(), stk::KERNEL_PANIC_ASSERT, m_owner_tid, m_recursion_count, stk::NO_WAIT, RECURSION_MAX, stk::IKernelService::RestoreWeight(), STK_ASSERT, stk::STK_KERNEL_PANIC(), stk::TID_NONE, stk::IKernelService::Wait(), stk::WAIT_RESULT_SIGNAL, and stk::WAIT_RESULT_TIMEOUT.
Referenced by Lock(), pthread_mutex_timedlock(), stk_mutex_timed_lock_ex(), and TimedLock().
|
inlinevirtual |
Try to acquire the lock without blocking.
Implements stk::IMutex.
Definition at line 112 of file stk_sync_mutex.h.
References stk::NO_WAIT, and TimedLock().
Referenced by pthread_mutex_trylock(), pthread_spin_trylock(), and stk_mutex_trylock().
|
inlineprivateinherited |
Remove this entry from its current list.
Definition at line 174 of file stk_linked_list.h.
|
inlineoverridevirtual |
Release lock.
Implements stk::IMutex.
Definition at line 259 of file stk_sync_mutex.h.
References stk::ISyncObject::FindWeightHigherThan(), stk::IKernelService::GetInstance(), stk::GetTid(), stk::IWaitObject::GetTid(), stk::GetUserTaskFromTid(), stk::SyncObjectBase::IKernelService, stk::IKernelService::InheritWeight(), stk::detail::DListCast::ListEntryToParent(), m_owner_tid, m_recursion_count, stk::SyncObjectBase::m_wait_list, stk::IKernelService::RestoreWeight(), STK_ASSERT, stk::TID_NONE, and stk::IWaitObject::Wake().
Referenced by MqReceiveImpl(), MqSendImpl(), pthread_mutex_unlock(), pthread_once(), pthread_rwlock_unlock(), pthread_spin_unlock(), and stk_mutex_unlock().
|
inlinestaticinherited |
Wake all tasks currently in the wait list.
| [in] | wlist | Wait list. |
Definition at line 752 of file stk_common.h.
References stk::detail::DListHead< T, TClosedLoop >::GetFirst(), and stk::detail::DListCast::ListEntryToParent().
|
inlineoverrideprotectedvirtualinherited |
Wake all tasks currently in the wait list.
Implements stk::ISyncObject.
Definition at line 301 of file stk_helper.h.
References stk::IKernelService::GetInstance(), and stk::IKernelService::Wake().
Referenced by stk::sync::ConditionVariable::NotifyAll_CS(), stk::sync::Event::Pulse(), and stk::sync::Event::Set().
|
inlinestaticinherited |
Wake the first task in the wait list (FIFO order).
| [in] | wlist | Wait list. |
Definition at line 736 of file stk_common.h.
References stk::detail::DListHead< T, TClosedLoop >::GetFirst(), stk::detail::DListCast::ListEntryToParent(), and stk::IWaitObject::Wake().
|
inlineoverrideprotectedvirtualinherited |
Wake the first task in the wait list (FIFO order).
Implements stk::ISyncObject.
Definition at line 296 of file stk_helper.h.
References stk::IKernelService::GetInstance(), and stk::IKernelService::Wake().
Referenced by stk::sync::ConditionVariable::NotifyOne_CS(), stk::sync::Event::Pulse(), stk::sync::Event::Set(), and stk::sync::SemaphoreT< T >::TrySignalLimited().
|
privateinherited |
Owning list head, or NULL when the entry is not linked.
Definition at line 191 of file stk_linked_list.h.
|
privateinherited |
Next entry in the list, or NULL (open list boundary) / first entry (closed loop).
Definition at line 192 of file stk_linked_list.h.
|
private |
thread id of the current owner
Definition at line 145 of file stk_sync_mutex.h.
Referenced by GetOwner(), IsLocked(), Mutex(), TimedLockEx(), and Unlock().
|
privateinherited |
Previous entry in the list, or NULL (open list boundary) / last entry (closed loop).
Definition at line 193 of file stk_linked_list.h.
|
private |
recursion depth
Definition at line 146 of file stk_sync_mutex.h.
Referenced by GetRecursionCount(), Mutex(), TimedLockEx(), and Unlock().
|
protectedinherited |
Tasks blocked on this object.
Definition at line 311 of file stk_helper.h.
Referenced by AddWaitObject(), GetMutableWaitList(), GetWaitList(), stk::sync::Event::Pulse(), RemoveWaitObject(), SyncObjectBase(), stk::sync::SemaphoreT< T >::TrySignalLimited(), stk::sync::FastMutex::Unlock(), stk::sync::Mutex::Unlock(), stk::sync::ConditionVariable::~ConditionVariable(), stk::sync::Event::~Event(), stk::sync::FastMutex::~FastMutex(), and stk::sync::Mutex::~Mutex().
|
static |
maximum nesting depth
Definition at line 57 of file stk_sync_mutex.h.
Referenced by stk::pthread::PreLockCheck(), and TimedLockEx().