Component bslmt_lockguard [Package bslmt]

Provide generic scoped guards for synchronization objects. More...

Namespaces
namespace	bslmt

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Behavior of the release Method
  • Usage

Purpose:

Provide generic scoped guards for synchronization objects.

Classes:

bslmt::LockGuard	automatic mutex locking-unlocking
bslmt::LockGuardUnlock	automatic mutex unlocking-locking
bslmt::LockGuardTryLock	automatic non-blocking mutex locking-unlocking
bslmt::UnLockGuard	DEPRECATED
bslmt::TryLockGuard	DEPRECATED

See also:

Component bslmt_readlockguard, Component bslmt_writelockguard

Description:

This component provides generic guards, bslmt::LockGuard, bslmt::LockGuardUnlock, and bslmt::LockGuardTryLock, to automatically lock and unlock an external synchronization object. The synchronization object can be any type (e.g., bslmt::Mutex or bslmt::RecursiveMutex) that provides the following methods:

  void lock();
  void unlock();

Both bslmt::LockGuard and bslmt::LockGuardUnlock implement the "construction is acquisition, destruction is release" idiom. During construction, bslmt::LockGuard automatically calls lock on the user-supplied object, and unlock when it is destroyed (unless released). bslmt::LockGuardUnlock does the opposite -- it invokes the unlock method when constructed and the lock method when it is destroyed.

A third type of guard, bslmt::LockGuardTryLock, attempts to acquire a lock, and if acquisition succeeds, releases it upon destruction. Since the acquisition is done at construction time, it is not possible to return a value to indicate success. Rather, the bslmt::LockGuardTryLock contains a pointer to the synchronization object if tryLock succeeds, and is null otherwise. The synchronization object can be any type (e.g., bslmt::Mutex or bslmt::RecursiveMutex) that provides the following methods:

  int  tryLock();
  void unlock();

Note that none of these guard types assumes ownership of the external synchronization object. Also note that objects of all of the guard types may be constructed with a null lock whereby the constructed guard objects manage no lock. The destructor of each of the guard types has no effect if no lock is under management.

Behavior of the release Method:

Like all BDE guard classes, each of the three bslmt::LockGuard* classes provides a release method that terminates the guard's management of any lock object that the guard holds. The release method has no effect on the state of the lock object.

In particular, bslmt::ReadLockGuard::release does not unlock the lock object under management. If a user wants to release the lock object and unlock the lock object (because the lock is no longer required before the guard goes out of scope), the following idiom can be used:

  // 'guard' is an existing guard of type 'bslmt::LockGuard<my_Lock>',
  // created in a scope that we do not control.

  {
      // ... Do work that requires the lock.

      // We know that the lock is no longer needed.

      my_Lock *lock = guard.release();

      // 'lock' is no longer managed, but is *still* *locked*.

      lock->unlock();

      // ... Do work that does not require the lock.
  }

Usage:

Use this component to ensure that in the event of an exception or exit from any point in a given scope, the synchronization object will be properly unlocked. The following function, errorProneFunc, is overly complex, not exception safe, and contains a bug.

  static void errorProneFunc(my_Object *obj, my_Mutex *mutex)
  {
      mutex->lock();
      if (someCondition) {
          obj->someMethod();
          mutex->unlock();
          return;                                                   // RETURN
      } else if (someOtherCondition) {
          obj->someOtherMethod();
          // MISTAKE! forgot to unlock mutex
          return;                                                   // RETURN
      }
      obj->defaultMethod();
      mutex->unlock();
      return;
  }

The function can be rewritten with a cleaner and safer implementation using a guard object. The safeFunc function is simpler than errorProneFunc, is exception safe, and avoids the multiple calls to unlock that can be a source of errors.

  static void safeFunc(my_Object *obj, my_Mutex *mutex)
  {
      bslmt::LockGuard<my_Mutex> guard(mutex);
      if (someCondition) {
          obj->someMethod();
          return;                                                   // RETURN
      } else if (someOtherCondition) {
          obj->someOtherMethod();
          // OK, mutex is automatically unlocked
          return;                                                   // RETURN
      }
      obj->defaultMethod();
      return;
  }

When blocking while acquiring the lock is not desirable, one may instead use a bslmt::LockGuardTryLock in the typical following fashion:

  static int safeButNonBlockingFunc(my_Object *obj, my_Mutex *mutex)
      // Perform task and return positive value if locking succeeds.  Return
      // 0 if locking fails.
  {
      const int RETRIES = 1; // use higher values for higher success rate
      bslmt::LockGuardTryLock<my_Mutex> guard(mutex, RETRIES);
      if (guard.ptr()) { // mutex is locked
          if (someCondition) {
              obj->someMethod();
              return 2;                                             // RETURN
          } else if (someOtherCondition) {
              obj->someOtherMethod();
              return 3;                                             // RETURN
          }
          obj->defaultMethod();
          return 1;                                                 // RETURN
      }
      return 0;
  }

Instantiations of bslmt::LockGuardUnlock can be interleaved with instantiations of bslmt::LockGuard to create both critical sections and regions where the lock is released.

  void f(my_Mutex *mutex)
  {
      bslmt::LockGuard<my_Mutex> guard(mutex);

      // critical section here

      {
          bslmt::LockGuardUnlock<my_Mutex> guard(mutex);

          // mutex is unlocked here

      } // mutex is locked again here

      // critical section here

  } // mutex is unlocked here

Care must be taken so as not to interleave guard objects in such a way as to cause an illegal sequence of calls on a lock (two sequential lock calls or two sequential unlock calls on a non-recursive mutex).