Programming Reference:OSMutex Class

From BCI2000 Wiki
Jump to: navigation, search

Location

BCI2000/src/shared/utils

Synopsis

The OSMutex class provides a wrapper for OS-dependent synchronization functionality, corresponding to a Windows or POSIX threads mutex object.

Methods

OSMutex()

Mutexes are created in released state, i.e. no thread owns the newly created mutex.

~OSMutex()

Releases all resources allocated for the mutex object.

bool Acquire()

Acquires ownership of the mutex for the current thread. When the mutex is owned by a different thread, the current thread is blocked until the owning thread calls Release() on the mutex object. When the mutex is already owned by the thread calling Acquire(), it does not block; rather, a lock count is increased, and the calling thread continues running. For each call to Acquire(), there must be a balancing call to Release() in order to make the mutex available to other threads. Acquire returns true when successful, and false otherwise.

bool Release()

Gives up ownership of the mutex for the current thread, or decreases the lock count when the mutex has been acquired multiple times by a thread. When multiple threads are waiting for the mutex, a random thread is unblocked. Returns true when successful, and false when an error occurred.

Sub-classes

OSMutex::Lock(OSMutex)

An object that acquires the specified mutex when created, and releases it when destructed.

OSMutex::Unlock(OSMutex)

An object that releases the specified mutex when created, and acquires it when destructed.

Use objects of type OSMutex::Lock and OSMutex::Unlock to make sure the mutex is restored to its previous state when the current scope is left. This is especially useful when it is possible that an exception is thrown while the mutex is in its altered state. During stack unwinding, the lock/unlock object's destructor is called, and the mutex is restored to its previous state, even when an exception is thrown.

See also

Programming Reference:OSThread Class, Programming Reference:OSEvent Class