Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is an old version of boost. Click here for the latest version's documentation home page.

C++ Boost

Boost.Threads

ScopedLock Concept


Introduction
Concept Requirements
Lock Concept
ScopedLock Concept
ScopedTryLock Concept
ScopedTimedLock Concept

Introduction

A lock object provides a safe means for locking and unlocking a mutex object (an object whose type is a model of Mutex or one of its refinements). In other words they are an implementation of the Scoped Locking [Schmidt 00] pattern. The ScopedLock concept, with ScopedTryLock and ScopedTimedLock refinements, formalize the requirements.

Lock objects are constructed with a reference to a mutex object and typically acquire ownership of the mutex object by setting its state to locked. They also ensure ownership is relinquished in the destructor. Lock objects also expose functions to query the lock status and to manually lock and unlock the mutex object.

Lock objects are meant to be short lived, expected to be used at block scope only. The lock objects are not thread-safe. Lock objects must maintain state to indicate whether or not they've been locked and this state is not protected by any synchronization concepts. For this reason a lock object should never be shared between multiple threads.

Concept Requirements

Lock Concept

For a Lock type L and an object lk and const object clk of that type, the following expressions must be well-formed and have the indicated effects.

Expression Effects
(&lk)->~L(); if (locked()) unlock();
(&clk)->operator const void*() Returns type void*, non-zero if if the associated mutex object has been locked by clk, otherwise 0.
clk.locked() Returns a bool, (&clk)->operator const void*() != 0
lk.lock() Throws lock_error if locked(). If the associated mutex object is already locked by some other thread, places the current thread in the Blocked state until the associated mutex is unlocked, after which the current thread is placed in the Ready state, eventually to be returned to the Running state. If the associated mutex object is already locked by the same thread the behavior is dependent on the locking strategy of the associated mutex object.
Postcondition: locked() == true
lk.unlock() If !locked(), throws lock_error, otherwise unlocks the associated mutex.
Postcondition: !locked()

ScopedLock Concept

A ScopedLock is a refinement of Lock. For a ScopedLock type L and an object lk of that type, and an object m of a type meeting the Mutex requirements, and an object b of type bool, the following expressions must be well-formed and have the indicated effects.

Expression Effects
L lk(m); Constructs an object lk, and associates mutex object m with it, then calls lock()
L lk(m,b); Constructs an object lk, and associates mutex object m with it, then if b, calls lock()

ScopedTryLock Concept

A ScopedTryLock is a refinement of Lock. For a ScopedTryLock type L and an object lk of that type, and an object m of a type meeting the TryMutex requirements, and an object b of type bool, the following expressions must be well-formed and have the indicated effects.

Expression Effects
L lk(m); Constructs an object lk, and associates mutex object m with it, then calls try_lock()
L lk(m,b); Constructs an object lk, and associates mutex object m with it, then if b, calls lock()
lk.try_lock() If locked(), throws lock_error. Makes a non-blocking attempt to lock the associated mutex object, returning true if the lock attempt is successful, otherwise false. If the associated mutex object is already locked by the same thread the behavior is dependent on the locking strategy of the associated mutex object.

ScopedTimedLock Concept

A ScopedTimedLock is a refinement of Lock. For a ScopedTimedLock type L and an object lk of that type, and an object m of a type meeting the TimedMutex requirements, and an object b of type bool, and an object t of type xtime, the following expressions must be well-formed and have the indicated effects.

Expression Effects
L lk(m,t); Constructs an object lk, and associates mutex object m with it, then calls timed_lock(t)
L lk(m,b); Constructs an object lk, and associates mutex object m with it, then if b, calls lock()
lk.timed_lock(t) If locked(), throws lock_error. Makes a blocking attempt to lock the associated mutex object, and returns true if successful within the specified time t, otherwise false. If the associated mutex object is already locked by the same thread the behavior is dependent on the locking strategy of the associated mutex object.

Revised 05 November, 2001

© Copyright William E. Kempf 2001-2002. All Rights Reserved.

Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. William E. Kempf makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.