cmlabs::utils::Mutex Class Reference

Recursive mutual-exclusion lock, optionally named for cross-process use. More...

#include <Utils.h>

Public Member Functions
	Mutex ()
	Create an anonymous, process-local mutex.
	Mutex (const char *name, bool force=false)
	Create or open a named, cross-process mutex.
	~Mutex ()
bool	enter ()
	Block until the mutex is acquired.
bool	enter (uint32 timeout, const char *errorMsg=NULL)
	Acquire with a timeout.
bool	leave ()
	Release the mutex.
void	setCancelSafe (bool on)
	Make this mutex cancellation-safe (POSIX only; no-op on Windows).

Protected Attributes
char *	name
bool	created
uint32	osid
uint32	total
uint32	count
pthread_mutex_t *	mutex

Detailed Description

Recursive mutual-exclusion lock, optionally named for cross-process use.

Unnamed mutexes are process-local; named mutexes are created in shared memory / as kernel objects so multiple processes can synchronize on the same name. Prefer the timeout overload of enter() in production code so a dead peer cannot deadlock the caller forever.

Definition at line 463 of file Utils.h.

Constructor & Destructor Documentation

Mutex() [1/2]

cmlabs::utils::Mutex::Mutex

(

)

Create an anonymous, process-local mutex.

Definition at line 1040 of file Utils.cpp.

References count, created, FALSE, mutex, name, osid, and total.

Mutex() [2/2]

cmlabs::utils::Mutex::Mutex	(	const char *	name,
		bool	force = false )

Create or open a named, cross-process mutex.

Parameters

name	Global name (namespaced by the shared system instance).
force	Re-initialize the underlying object even if it already exists.

Definition at line 1068 of file Utils.cpp.

References count, created, cmlabs::utils::CreateSharedMemorySegment(), FALSE, MAXSHMEMNAMELEN, mutex, MUTEXMEMSIZE, name, cmlabs::utils::OpenSharedMemorySegment(), osid, total, and WINSHMEMSPACE.

~Mutex()

cmlabs::utils::Mutex::~Mutex

(

)

Definition at line 1123 of file Utils.cpp.

References cmlabs::utils::CloseSharedMemorySegment(), created, mutex, MUTEXMEMSIZE, name, and setCancelSafe().

Member Function Documentation

enter() [1/2]

bool cmlabs::utils::Mutex::enter

(

)

Block until the mutex is acquired.

Returns

true when acquired.

Definition at line 1158 of file Utils.cpp.

References count, cmlabs::utils::g_savedCancelState, cmlabs::utils::GetCurrentThreadOSID(), LOG_SYSTEM, LogPrint, mutex, cmlabs::utils::MutexIsCancelSafe(), name, osid, and total.

Referenced by cmlabs::ConcResizer(), cmlabs::ConcWriter(), cmlabs::PsySpace::emitSignal(), cmlabs::utils::EnterMutex(), cmlabs::ThreadManager::UnitTest(), and cmlabs::PsySpace::waitForSignal().

enter() [2/2]

bool cmlabs::utils::Mutex::enter	(	uint32	timeout,
		const char *	errorMsg = NULL )

Acquire with a timeout.

Parameters

timeout	Max wait in milliseconds.
errorMsg	Optional label (typically FUNCTION) logged when the wait times out.

Returns

true when acquired, false on timeout/error.

Definition at line 1214 of file Utils.cpp.

References cmlabs::utils::CalcTimeout(), count, cmlabs::utils::g_savedCancelState, cmlabs::utils::GetCurrentThreadOSID(), LOG_SYSTEM, LogPrint, mutex, cmlabs::utils::MutexIsCancelSafe(), osid, and total.

leave()

bool cmlabs::utils::Mutex::leave

(

)

Release the mutex.

Returns

true on success.

Definition at line 1330 of file Utils.cpp.

References count, cmlabs::utils::g_savedCancelState, mutex, cmlabs::utils::MutexIsCancelSafe(), and osid.

Referenced by cmlabs::ConcResizer(), cmlabs::ConcWriter(), cmlabs::PsySpace::emitSignal(), cmlabs::MemoryRequestConnection::shutdown(), cmlabs::ThreadManager::UnitTest(), and cmlabs::PsySpace::waitForSignal().

setCancelSafe()

void cmlabs::utils::Mutex::setCancelSafe

(

bool

on

)

Make this mutex cancellation-safe (POSIX only; no-op on Windows).

When enabled, enter() disables thread cancellation BEFORE acquiring and leave() restores it on the outermost release. This guarantees a thread can never be cancelled (deferred OR asynchronous) while holding the lock, so pthread_cancel() during teardown cannot orphan the mutex and hang every later waiter. Off by default so ordinary mutexes are byte-for-byte unchanged; enable only where holders may be force-terminated (e.g. the ThreadManager registry lock). Requires balanced enter()/leave() pairing.

IMPORTANT: the "cancel-safe" bit is stored OUT-OF-LINE (in a side registry keyed by mutex pointer, see Utils.cpp) and the saved cancel state lives in a thread-local. This keeps sizeof(Mutex) and its member layout BYTE-IDENTICAL to the original — Mutex is embedded by value in structs that are sensitive to its size/layout (PsySpace, network connections, SWIG-wrapped types), and growing it corrupted those on the Linux libPsySystem.so build.

Definition at line 1016 of file Utils.cpp.

References cmlabs::utils::g_cancelSafeCount, cmlabs::utils::g_cancelSafeSet, and cmlabs::utils::g_cancelSafeSetLock.

Referenced by ~Mutex().

Member Data Documentation

count

uint32 cmlabs::utils::Mutex::count

protected

Definition at line 504 of file Utils.h.

Referenced by enter(), enter(), leave(), Mutex(), and Mutex().

created

bool cmlabs::utils::Mutex::created

protected

Definition at line 501 of file Utils.h.

Referenced by Mutex(), Mutex(), and ~Mutex().

mutex

pthread_mutex_t* cmlabs::utils::Mutex::mutex

protected

Definition at line 509 of file Utils.h.

Referenced by enter(), enter(), leave(), Mutex(), Mutex(), and ~Mutex().

name

char* cmlabs::utils::Mutex::name

protected

Definition at line 500 of file Utils.h.

Referenced by enter(), Mutex(), Mutex(), and ~Mutex().

osid

uint32 cmlabs::utils::Mutex::osid

protected

Definition at line 502 of file Utils.h.

Referenced by enter(), enter(), leave(), Mutex(), and Mutex().

total

uint32 cmlabs::utils::Mutex::total

protected

Definition at line 503 of file Utils.h.

Referenced by enter(), enter(), Mutex(), and Mutex().

---

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

• /home/ubuntu/c/partner/psyclone2/CMSDK/include/Utils.h
• /home/ubuntu/c/partner/psyclone2/CMSDK/src/Utils.cpp