C++ Boost

Boost.Threads

scoped_lock


Introduction
Header
Synopsis
Members
Example

Introduction

This class template defines a generic lock type which meets the ScopedLock requirements. The mutex, try_mutex, timed_mutex, recursive_mutex, recursive_try_mutex and recursive_timed_mutex classes all use this template to define their scoped_lock types.

Like all the Boost.Threads lock models, scoped_lock objects are meant to be short-lived. Objects of the class are not thread-safe, and so should not be shared between threads.

Class scoped_lock follows the "resource acquisition is initialization" idiom [Stroustrup 00 14.4.1] and is a realization of the "Scoped Locking Pattern" [Schmidt-00]. Thus the usage is to let the constructor do the locking, and then let the destructor do the unlocking automatically at the end of the enclosing scope. The lock() and unlock() members are usually not explicitly called, but are provided to allow for complex overlapping locks of multiple mutexes.

The type used to instantiate the class must meet the Mutex requirements.

Although this class is an implementation detail, it is publicly documented here because of its importance.

Header

#include <boost/thread/detail/lock.hpp>
    This header is usually not included directly by programmers
    because it is supplied by <boost/thread/mutex.hpp> or
    <boost/thread/recursive_mutex.hpp>

Synopsis

namespace boost { namespace detail { namespace thread {
    template <typename Mutex>
    class scoped_lock : private boost::noncopyable // Exposition only.
        // Class scoped_lock meets the NonCopyable requirement.
    {
    public:
        typedef Mutex mutex_type;
        
        explicit scoped_lock(Mutex& mx, bool initially_locked=true);
        ~scoped_lock();
        
        void lock();
        void unlock();
        
        operator const void*() const;
        bool locked() const;
    };
} // namespace thread
} // namespace detail
} // namespace boost

Members


Constructor

    explicit scoped_lock(Mutex& mx, bool initially_locked=true);

Effects: Associates mutex mx with *this. If initially_locked is true, calls lock().


Destructor

    ~scoped_lock();

Effects: If locked(), calls unlock(). Destroys *this.


lock

    void lock();

Effects: If the associated mutex is already locked by another lock in the current thread, the effects depend on the locking strategy of the associated mutex, as shown in the following table:

Locking Strategy
of associated mutex
Effect if associated mutex is already locked by the current thread
Recursive As if an additional lock were added to the mutex.
Checked Throws lock_error.
Unchecked Undefined behavior [ISO 1.3.12] (but typically, deadlock.)

If the associated mutex 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.

Postcondition: locked()

Throws: lock_error if locked() or as indicated in Effects.


unlock

    void unlock();

Effects: Unlocks the associated mutex.

Throws: lock_error if !locked().


const void* Conversion

    operator const void*() const;

Returns: If the associated mutex is currently locked, a value convertible to true, else a value convertible to false.

Rationale: A const void* conversion is considered safer than a conversion to bool.


locked

    bool locked() const;

Returns: this->operator const void*() != 0.


Example Usage

See the example given in the documentation for the mutex class.


Revised 05 November, 2001

© Copyright William E. Kempf 2001 all rights reserved.