bslmt_recursivemutex

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Basic Usage

Purpose

Provide a platform-independent recursive mutex.

Classes

• bslmt::RecursiveMutex: platform-independent recursive mutex

See also

bslmt_mutex

Description

This component provides a mutually exclusive lock primitive ("mutex") that is "recursive" - a given thread can lock a recursive mutex multiple times, and then release it by unlocking it the same number of times. The bslmt::RecursiveMutex class provides the following operations: lock, tryLock, and unlock.

The non-recursive mutex bslmt::Mutex has substantially lower overhead than bslmt::RecursiveMutex, and should be used instead if at all possible. In particular, it is rare to need a recursive mutex.

The behavior is undefined if unlock is invoked on a bslmt::RecursiveMutex object from a thread that does not currently own the lock.

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage

As the name implies, bslmt::RecursiveMutex supports multiple calls to lock, which must be balanced by a corresponding number of calls to unlock. Suppose that we are using a bslmt::RecursiveMutex object to guarantee exclusive access to some object. The following sketches the "recursive" nature of bslmt::RecursiveMutex:

bslmt::RecursiveMutex recMutex;

Assume that we do not have exclusive access to the object.

recMutex.lock();    // first level of locking

We have exclusive access here.

recMutex.lock();    // second level of locking

We still have exclusive access.

recMutex.unlock();  // release second level lock -- mutex stays locked

We still have exclusive access.

recMutex.unlock();  // release first level lock -- mutex is unlocked

The two calls to unlock have balanced the two earlier calls to lock. Consequently, we no longer have exclusive access.

Note that bslmt::RecursiveMutex has substantially more overhead than does bslmt::Mutex. Consequently, the latter should be used unless recursive locking is truly warranted.