Component bslmt_recursivemutex [Package bslmt]

Provide a platform-independent recursive mutex. More...

Namespaces
namespace	bslmt

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage

Purpose:

Provide a platform-independent recursive mutex.

Classes:

bslmt::RecursiveMutex

platform-independent recursive mutex

See also:

Component 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:

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.