Boost.Threads

basic_lock

Introduction
Header
Synopsis
Members
Example

Introduction

This class template defines a generic lock concept type. The mutex, try_mutex, timed_mutex, recursive_mutex, recursive_try_mutex and recursive_timed_mutex classes all use this template to define their lock types. Instances of class basic_lock meet the Lock requirements.

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

Class basic_lock follows the "resource acquisition is initialization" idiom [Stroustrup 00 14.4.1]. Thus a common 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 commonly not explicitly called.

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

Header

#include <boost/thread/xlock.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 {

    template <typename M>
    class basic_lock : private boost::noncopyable
    {
    public:
        typedef M mutex_type;
        
        explicit basic_lock(M& mx, bool lock_it=true);
        ~basic_lock();
        
        void lock();
        void unlock();
        
        operator const void*() const;
    };

} // namespace boost

Members

Constructor

    explicit basic_lock(M& mx, bool lock_it=true);

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

Destructor

    ~basic_lock();

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

lock

    void lock();

Requires: If the locking strategy of the associated mutex is anything other than recursive, the associated mutex must not already be locked.

Effects: If the associated mutex is not already locked, locks it. Otherwise, the effect depends 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
Recursive	As if an additional lock were added to the mutex.
Checked	Throws lock_error.
Unspecified	Undefined behavior [ISO 1.3.12] (but typically, deadlock.)

unlock

    void unlock();

Effects: Unlocks the associated mutex.

Throws: lock_error if the associated mutex is not already 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.

Example Usage

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

Revised 19 July, 2001