RWFIFOMutexLock Class Reference

Guarantees that blocking threads acquire the mutex in the same order that they called the acquire() member function. More...

#include <rw/sync/RWFIFOMutexLock.h>

Inheritance diagram for RWFIFOMutexLock:

Public Types
typedef RWTLockGuard< RWFIFOMutexLock >	LockGuard
typedef RWTLockGuard< RWFIFOMutexLock >	ReadLockGuard
typedef RWTUnlockGuard< RWFIFOMutexLock >	ReadUnlockGuard
typedef RWTTryLockGuard< RWFIFOMutexLock >	TryLockGuard
typedef RWTTryLockGuard< RWFIFOMutexLock >	TryReadLockGuard
typedef RWTTryLockGuard< RWFIFOMutexLock >	TryWriteLockGuard
typedef RWTUnlockGuard< RWFIFOMutexLock >	UnlockGuard
typedef RWTLockGuard< RWFIFOMutexLock >	WriteLockGuard
typedef RWTUnlockGuard< RWFIFOMutexLock >	WriteUnlockGuard

Public Member Functions
	RWFIFOMutexLock (RWCancellationState state=0)
	RWFIFOMutexLock (RWStaticCtor)
	~RWFIFOMutexLock ()
void	acquire ()
RWWaitStatus	acquire (unsigned long milliseconds)
void	acquireRead ()
RWWaitStatus	acquireRead (unsigned long milliseconds)
void	acquireWrite ()
RWWaitStatus	acquireWrite (unsigned long milliseconds)
bool	isAcquired () const
void	release ()
bool	tryAcquire ()
bool	tryAcquireRead ()
bool	tryAcquireWrite ()
Public Member Functions inherited from RWSynchObject
void	disableCancellation ()
void	enableCancellation (RWCancellationState)
bool	isCancellationEnabled () const
void	setCancellation (RWCancellationState)

Private Member Functions
	RWFIFOMutexLock (const RWFIFOMutexLock &second)
RWFIFOMutexLock &	operator= (const RWFIFOMutexLock &second)

Additional Inherited Members
Protected Member Functions inherited from RWSynchObject
	RWSynchObject (RWCancellationState state=0)
	RWSynchObject (RWStaticCtor)
	RWSynchObject (const RWSynchObject &second)
RWSynchObject &	operator= (const RWSynchObject &second)
void	testCancellation ()
Related Functions inherited from RWSynchObject
#define	RW_CANCELLATION_DISABLED
#define	RW_CANCELLATION_ENABLED
typedef void(*	RWCancellationState) ()
void	rwServiceCancellation (void)

Detailed Description

An RWFIFOMutexLock can be used to guarantee that blocking threads acquire the mutex in the same order that they called the acquire() member function. On certain systems, thread attributes such as thread priority may be a factor in determining the order in which threads blocking on the same mutex acquire that mutex when it is finally released. Class RWFIFOMutexLock eliminates any other factors and considers only the order of requests for acquisition.

Example

#include <rw/sync/RWFIFOMutexLock.h>

int main()
{
    RWFIFOMutexLock fifomutex;
    fifomutex.acquire();
    // critical section
    fifomutex.release();

    // Same thing, this time using a guard:
    {
        RWFIFOMutexLock::LockGuard lock(fifomutex);
        // critical section

        // Mutex will be released in RWFIFOMutexLock::LockGuard
        // destructor before leaving scope, especially important
        // if an exception is thrown!
    }

    return 0;
}

See also

RWMutexLock, RWTRecursiveLock

Member Typedef Documentation

typedef RWTLockGuard<RWFIFOMutexLock> RWFIFOMutexLock::LockGuard

Predefined type for compatible guard.

typedef RWTLockGuard<RWFIFOMutexLock> RWFIFOMutexLock::ReadLockGuard

Predefined type for compatible guard.

typedef RWTUnlockGuard<RWFIFOMutexLock> RWFIFOMutexLock::ReadUnlockGuard

Predefined type for compatible guard.

typedef RWTTryLockGuard<RWFIFOMutexLock> RWFIFOMutexLock::TryLockGuard

Predefined type for compatible guard.

typedef RWTTryLockGuard<RWFIFOMutexLock> RWFIFOMutexLock::TryReadLockGuard

Predefined type for compatible guard.

typedef RWTTryLockGuard<RWFIFOMutexLock> RWFIFOMutexLock::TryWriteLockGuard

Predefined type for compatible guard.

typedef RWTUnlockGuard<RWFIFOMutexLock> RWFIFOMutexLock::UnlockGuard

Predefined type for compatible guard.

typedef RWTLockGuard<RWFIFOMutexLock> RWFIFOMutexLock::WriteLockGuard

Predefined type for compatible guard.

typedef RWTUnlockGuard<RWFIFOMutexLock> RWFIFOMutexLock::WriteUnlockGuard

Predefined type for compatible guard.

Constructor & Destructor Documentation

RWFIFOMutexLock::RWFIFOMutexLock ( RWCancellationState  state = 0 )

inline

Creates and initializes an RWFIFOMutexLock. The thread cancellation state of the object is initialized to state.

RWFIFOMutexLock::RWFIFOMutexLock ( RWStaticCtor  )

inline

Constructs a static instance, but does no direct initialization. The RWFIFOMutexLock is initialized on first use.

This constructor must be used only for static instances. Use of this constructor with an automatically or dynamically allocated instance produces errors or other unpredictable behavior.

Static instances are zero initialized, which results in an RWFIFOMutexLock with cancellation state of RW_CANCELLATION_DISABLED.

Note

This constructor functions correctly only in single-threaded builds, due to the presence of some data members that do not implement a constructor with an RWStaticCtor argument.

RWFIFOMutexLock::~RWFIFOMutexLock ( )

inline

Recovers any system resources used to implement the RWFIFOMutexLock.

RWFIFOMutexLock::RWFIFOMutexLock ( const RWFIFOMutexLock &  second )

private

Copy construction prohibited.

Member Function Documentation

void RWFIFOMutexLock::acquire

(

)

Causes the current thread to block until the mutex is released, at which time the thread acquires the mutex and continues. If other threads are blocked waiting for this same mutex, the first thread that called this member function acquires the mutex and continues. Possible exceptions include RWCancellation and RWTHRInternalError.

In single-threaded builds, this method does not block. On success, it returns immediately; otherwise it fails with a debug assertion in debug mode, or a thrown RWTHRInternalError in release builds.

RWWaitStatus RWFIFOMutexLock::acquire

(

unsigned long

milliseconds

)

Blocks at least for the specified number of milliseconds, or until the mutex is released, whichever comes first. If the mutex is released within the specified time, acquires it and continues. If the mutex is not released, returns RW_THR_TIMEOUT. Possible exceptions include RWCancellation and RWTHRInternalError.

In single-threaded builds, this method immediately returns RW_THR_ACQUIRED if the resource is currently available, otherwise returns RW_THR_TIMEOUT.

void RWFIFOMutexLock::acquireRead ( )

inline

Calls acquire(). Provided for compatibility with Read/Write locks. Possible exceptions include RWCancellation and RWTHRInternalError.

RWWaitStatus RWFIFOMutexLock::acquireRead ( unsigned long  milliseconds )

inline

Calls acquire(milliseconds). Provided for compatibility with Read/Write locks. Possible exceptions include RWCancellation and RWTHRInternalError.

void RWFIFOMutexLock::acquireWrite ( )

inline

Calls acquire(). Provided for compatibility with Read/Write locks. Possible exceptions include RWCancellation and RWTHRInternalError.

RWWaitStatus RWFIFOMutexLock::acquireWrite ( unsigned long  milliseconds )

inline

Calls acquire(milliseconds). Provided for compatibility with Read/Write locks. Possible exceptions include RWCancellation and RWTHRInternalError.

bool RWFIFOMutexLock::isAcquired

(

)

const

Determines whether the calling thread currently owns the mutex.

Condition:

Available only from the debug version of the Threads Module.

RWFIFOMutexLock& RWFIFOMutexLock::operator= ( const RWFIFOMutexLock &  second )

private

Assignment prohibited.

void RWFIFOMutexLock::release

(

)

Releases the mutex, making it available. Possible exceptions include RWTHRInternalError.

bool RWFIFOMutexLock::tryAcquire

(

)

Tries to acquire mutex without blocking. Returns true if successful, otherwise false. Possible exceptions include RWCancellation and RWTHRInternalError.

bool RWFIFOMutexLock::tryAcquireRead ( )

inline

Calls tryAcquire(). Provided for compatibility with Read/Write locks. Possible exceptions include RWCancellation and RWTHRInternalError.

bool RWFIFOMutexLock::tryAcquireWrite ( )

inline

Calls tryAcquire(). Provided for compatibility with Read/Write locks. Possible exceptions include RWCancellation and RWTHRInternalError.