Boost.Threads

recursive_mutex

The recursive_mutex, recursive_try_mutex and recursive_timed_mutex classes define full featured mutex models with recursive locking semantics. These models should be used to synchronize access to shared resources when recursive locking by a single thread is likely to occur. A good example for this is when a class supplies "internal synchronization" to insure thread safety and a method on the class may have to call other methods on the class which would also attempt to lock the mutex model.

Each type adds another lock concept, including the basic_lock, basic_trylock and basic_timedlock types. For the best possible performance you should use the mutex type that supports only the lock types that you need.

The recursive_mutex, recursive_try_mutex and recursive_timed_mutex employ a Recursive locking strategy, so attempts to recursively lock them succeed and an internal "lock count" is maintained. Attempts to unlock them by a thread that does not own a lock on them will result in a lock_error exception being thrown.

Like all the Boost.Threads mutex models, the recursive_mutex, recursive_try_mutex and recursive_timed_mutex leave the scheduling policy as Unspecified. Programmers should assume that threads waiting for a lock on them shall acquire the lock in a random order, though the specific behavior for a given platform may be different.

Header

#include <boost/thread/recursive_mutex.hpp>

Public Interface

    class recursive_mutex : private boost::noncopyable
    {
    public:
       typedef boost::basic_lock<recursive_mutex> lock;
      
       recursive_mutex();
       ~recursive_mutex();
    };

Constructor

    recursive_mutex();

Constructs a recursive_mutex.

Destructor

    ~recursive_mutex();

Destructs a recursive_mutex.

    class recursive_try_mutex : private boost::noncopyable
    {
    public:
       typedef boost::basic_lock<recursive_try_mutex> lock;
       typedef boost::basic_trylock<recursive_try_mutex> try_lock;
      
       recursive_try_mutex();
       ~recursive_try_mutex();
    };

Constructor

    recursive_try_mutex();

Constructs a recursive_try_mutex.

Destructor

    ~recursive_try_mutex();

Destructs a recursive_try_mutex.

    class recursive_timed_mutex : private boost::noncopyable
    {
    public:
       typedef boost::basic_lock<recursive_timed_mutex> lock;
       typedef boost::basic_trylock<recursive_timed_mutex> try_lock;
       typedef boost::basic_timedlock<recursive_timed_mutex> timed_lock;
      
       recursive_timed_mutex();
       ~recursive_timed_mutex();
    };

Constructor

    recursive_timed_mutex();

Constructs a recursive_timed_mutex.

Destructor

    ~recursive_timed_mutex();

Destructs a recursive_timed_mutex.

Example Usage

#include <boost/thread/recursive_mutex.hpp>
#include <boost/thread/thread.hpp>
#include <iostream>

class counter
{
private:
    boost::recursive_mutex mutex;
    int count;
   
public:
    counter() : count(0) { }

    int add(int val) {
        boost::recursive_mutex::lock lock(mutex);
        count += val;
        return count;
    }   
    int increment() {
        boost::recursive_mutex::lock lock(mutex);
        return add(1);
    }
};

counter c;

void change_count(void*)
{
    std::cout << "count == " << c.increment() << std::endl;
}

int main(int, char*[])
{
    const int num_threads=4;
   
    for (int i=0; i < num_threads; ++i)
        boost::thread::create(&change_count, 0);
      
    boost::thread::join_all();
   
    return 0;
}

The output is:

count == 1
count == 2
count == 3
count == 4