The Mutex Class. Class providing Mutual-exclusion locks, based on BlockingObject. More...

#include <mutex.h>

Inheritance diagram for Mark3::Mutex:

Public Member Functions
void *	operator new (size_t sz, void *pv)

	~Mutex ()

void	Init (bool bRecursive_=true)
	Init Initialize a mutex object for use - must call this function before using the object. More...

void	Claim ()
	Claim Claim the mutex. When the mutex is claimed, no other thread can claim a region protected by the object. If another Thread currently holds the Mutex when the Claim method is called, that Thread will block until the current owner of the mutex releases the Mutex. More...

bool	Claim (uint32_t u32WaitTimeMS_)
	Claim Claim a mutex, with timeout. More...

void	WakeMe (Thread *pclOwner_)
	WakeMe Wake a thread blocked on the mutex. This is an internal function used for implementing timed mutexes relying on timer callbacks. Since these do not have access to the private data of the mutex and its base classes, we have to wrap this as a public method - do not use this for any other purposes. More...

void	Release ()
	Release Release the mutex. When the mutex is released, another object can enter the mutex-protected region. More...

Public Member Functions inherited from Mark3::BlockingObject
	BlockingObject ()

	~BlockingObject ()

Private Member Functions
uint8_t	WakeNext ()
	WakeNext. More...

bool	Claim_i (uint32_t u32WaitTimeMS_)
	Claim_i Abstracts out timed/non-timed mutex claim operations. More...

Private Attributes
uint8_t	m_u8Recurse
	The recursive lock-count when a mutex is claimed multiple times by the same owner. More...

bool	m_bReady
	State of the mutex - true = ready, false = claimed. More...

bool	m_bRecursive
	Whether or not the lock is recursive. More...

PORT_PRIO_TYPE	m_uMaxPri
	Maximum priority of thread in queue, used for priority inheritence. More...

Thread *	m_pclOwner
	Pointer to the thread that owns the mutex (when claimed) More...

Additional Inherited Members
Protected Member Functions inherited from Mark3::BlockingObject
void	Block (Thread *pclThread_)
	Block Blocks a thread on this object. This is the fundamental operation performed by any sort of blocking operation in the operating system. All semaphores/mutexes/sleeping/messaging/etc ends up going through the blocking code at some point as part of the code that manages a transition from an "active" or "waiting" thread to a "blocked" thread. More...

void	BlockPriority (Thread *pclThread_)
	BlockPriority Same as Block(), but ensures that threads are added to the block-list in priority-order, which optimizes the unblock procedure. More...

void	UnBlock (Thread *pclThread_)
	UnBlock Unblock a thread that is already blocked on this object, returning it to the "ready" state by performing the following steps: More...

void	SetInitialized (void)
	SetInitialized. More...

bool	IsInitialized (void)
	IsInitialized. More...

Protected Attributes inherited from Mark3::BlockingObject
ThreadList	m_clBlockList

uint8_t	m_u8Initialized

Static Protected Attributes inherited from Mark3::BlockingObject
static constexpr auto	m_uBlockingInvalidCookie = uint8_t { 0x3C }

static constexpr auto	m_uBlockingInitCookie = uint8_t { 0xC3 }

Detailed Description

The Mutex Class. Class providing Mutual-exclusion locks, based on BlockingObject.

Examples:: lab5_mutexes/main.cpp.

Definition at line 63 of file mutex.h.

Constructor & Destructor Documentation

◆ ~Mutex()

Mark3::Mutex::~Mutex ( )

Definition at line 55 of file mutex.cpp.

Member Function Documentation

◆ Claim() [1/2]

void Mark3::Mutex::Claim ( void )

Claim Claim the mutex. When the mutex is claimed, no other thread can claim a region protected by the object. If another Thread currently holds the Mutex when the Claim method is called, that Thread will block until the current owner of the mutex releases the Mutex.

If the calling Thread's priority is lower than that of a Thread that currently owns the Mutex object, then the priority of that Thread will be elevated to that of the highest-priority calling object until the Mutex is released. This property is known as "Priority Inheritence"

Note: A single thread can recursively claim a mutex up to a count of

Attempting to claim a mutex beyond that will cause a kernel panic.

Examples:: lab5_mutexes/main.cpp.

Definition at line 185 of file mutex.cpp.

◆ Claim() [2/2]

bool Mark3::Mutex::Claim ( uint32_t u32WaitTimeMS_ )

Claim Claim a mutex, with timeout.

Parameters

u32WaitTimeMS_

Returns: true - mutex was claimed within the time period specified false - mutex operation timed-out before the claim operation.

Definition at line 191 of file mutex.cpp.

◆ Claim_i()

bool Mark3::Mutex::Claim_i ( uint32_t u32WaitTimeMS_ )

private

Claim_i Abstracts out timed/non-timed mutex claim operations.

Parameters

u32WaitTimeMS_ Time in MS to wait, 0 for infinite

Returns: true on successful claim, false otherwise

Definition at line 108 of file mutex.cpp.

◆ Init()

void Mark3::Mutex::Init ( bool bRecursive_ = true )

Init Initialize a mutex object for use - must call this function before using the object.

Parameters

bRecursive_ Whether or not the mutex can be recursively locked.

Definition at line 93 of file mutex.cpp.

◆ operator new()

void* Mark3::Mutex::operator new	(	size_t	sz,
		void *	pv
	)

inline

Definition at line 66 of file mutex.h.

◆ Release()

void Mark3::Mutex::Release ( )

Release Release the mutex. When the mutex is released, another object can enter the mutex-protected region.

If there are Threads waiting for the Mutex to become available, then the highest priority Thread will be unblocked at this time and will claim the Mutex lock immediately - this may result in an immediate context switch, depending on relative priorities.

If the calling Thread's priority was boosted as a result of priority inheritence, the Thread's previous priority will also be restored at this time.

Note that if a Mutex is held recursively, it must be Release'd the same number of times that it was Claim'd before it will be availabel for use by another Thread.

Examples:: lab5_mutexes/main.cpp.

Definition at line 197 of file mutex.cpp.

◆ WakeMe()

void Mark3::Mutex::WakeMe ( Thread * pclOwner_ )

WakeMe Wake a thread blocked on the mutex. This is an internal function used for implementing timed mutexes relying on timer callbacks. Since these do not have access to the private data of the mutex and its base classes, we have to wrap this as a public method - do not use this for any other purposes.

Parameters

pclOwner_ Thread to unblock from this object.

Definition at line 65 of file mutex.cpp.

◆ WakeNext()

uint8_t Mark3::Mutex::WakeNext ( )

private

WakeNext.

Wake the next thread waiting on the Mutex.

Definition at line 73 of file mutex.cpp.

Member Data Documentation

◆ m_bReady

bool Mark3::Mutex::m_bReady

private

State of the mutex - true = ready, false = claimed.

Definition at line 159 of file mutex.h.

◆ m_bRecursive

bool Mark3::Mutex::m_bRecursive

private

Whether or not the lock is recursive.

Definition at line 160 of file mutex.h.

◆ m_pclOwner

Thread* Mark3::Mutex::m_pclOwner

private

Pointer to the thread that owns the mutex (when claimed)

Definition at line 162 of file mutex.h.

◆ m_u8Recurse

uint8_t Mark3::Mutex::m_u8Recurse

private

The recursive lock-count when a mutex is claimed multiple times by the same owner.

Definition at line 158 of file mutex.h.

◆ m_uMaxPri

PORT_PRIO_TYPE Mark3::Mutex::m_uMaxPri

private

Maximum priority of thread in queue, used for priority inheritence.

Definition at line 161 of file mutex.h.

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

/mnt/c/Users/moslevin/m3-repo2/kernel/src/public/mutex.h
/mnt/c/Users/moslevin/m3-repo2/kernel/src/mutex.cpp

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ~Mutex()

Member Function Documentation

◆ Claim() [1/2]

◆ Claim() [2/2]

◆ Claim_i()

◆ Init()

◆ operator new()

◆ Release()

◆ WakeMe()

◆ WakeNext()

Member Data Documentation

◆ m_bReady

◆ m_bRecursive

◆ m_pclOwner

◆ m_u8Recurse

◆ m_uMaxPri