C++ Boost

Boost.Threads

recursive_mutex
recursive_try_mutex
recursive_timed_mutex


Introduction
Header
Class recursive_mutex Synopsis
Class recursive_mutex Members
Class recursive_try_mutex Synopsis
Class recursive_try_mutex Members
Class recursive_timed_mutex Synopsis
Class recursive_timed_mutex Members
Example

Introduction

The recursive_mutex, recursive_try_mutex and recursive_timed_mutex classes define full featured models of the Mutex, TryMutex and TimedMutex concepts with recursive locking semantics. These types 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 ensure thread-safety and a function of the class may have to call other functions of the class which also attempt to lock the mutex. For recursive locking mechanics, see mutexes.

Each class supplies one or more typedefs for lock types which model matching lock concepts. For the best possible performance you should use the mutex class that supports the minimum set of lock types that you need.

Mutex Class Lock name Implementation defined Lock Type Lock Concept
recursive_mutex scoped_lock detail::thread::scoped_lock<recursive_mutex> ScopedLock
recursive_try_mutex scoped_lock
scoped_try_lock
detail::thread::scoped_lock<recursive_try_mutex>
detail::thread::scoped_try_lock<recursive_try_mutex>
ScopedLock
ScopedTryLock
recursive_timed_mutex scoped_lock
scoped_try_lock
scoped_timed_lock
detail::thread::scoped_lock<recursive_timed_mutex>
detail::thread::scoped_try_lock<recursive_timed_mutex>
detail::thread::scoped_timed_lock<recursive_timed_mutex>
ScopedLock
ScopedTryLock
ScopedTimedLock

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.

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 objects of these types acquire the lock in a random order, even though the specific behavior for a given platform may be different.

Header

#include <boost/thread/recursive_mutex.hpp>

Class recursive_mutex Synopsis


namespace boost
{
   class recursive_mutex : private boost::noncopyable // Exposition only.
        // Class recursive_mutex meets the NonCopyable requirement.
   {
   public:
      typedef [implementation defined; see Introduction] scoped_lock;
      
      recursive_mutex();
      ~recursive_mutex();
   };
}

Class recursive_mutex Members


Constructor

    recursive_mutex();

Postconditions: *this is in the unlocked state.


Destructor

    ~recursive_mutex();

Requires: *this is in the unlocked state.

Effects: Destroys *this.

Dangers: Destruction of a locked mutex is a serious programming error resulting in undefined behavior such as a program crash..


Class recursive_try_mutex Synopsis

namespace boost
{
    class recursive_try_mutex : private boost::noncopyable // Exposition only.
        // Class recursive_try_mutex meets the NonCopyable requirement.
    {
    public:
       typedef [implementation defined; see Introduction] scoped_lock;
       typedef [implementation defined; see Introduction] scoped_try_lock;
      
       recursive_try_mutex();
       ~recursive_try_mutex();
    };
}

Class recursive_try_mutex Members


Constructor

    recursive_try_mutex();

Postconditions: *this is in the unlocked state.


Destructor

    ~recursive_try_mutex();

Requires: *this is in the unlocked state.

Effects: Destroys *this.

Dangers: Destruction of a locked mutex is a serious programming error resulting in undefined behavior such as a program crash..


Class recursive_timed_mutex Synopsis

namespace boost
{
    class recursive_timed_mutex : private boost::noncopyable // Exposition only.
        // Class recursive_timed_mutex meets the NonCopyable requirement.
    {
    public:
       typedef [implementation defined; see Introduction] scoped_lock;
       typedef [implementation defined; see Introduction] scoped_try_lock;
       typedef [implementation defined; see Introduction] scoped_timed_lock;
      
       recursive_timed_mutex();
       ~recursive_timed_mutex();
    };
}

Class recursive_timed_mutex Members


Constructor

    recursive_timed_mutex();

Postconditions: *this is in the unlocked state.


Destructor

    ~recursive_timed_mutex();

Requires: *this is in the unlocked state.

Effects: Destroys *this.

Dangers: Destruction of a locked mutex is a serious programming error resulting in undefined behavior such as a program crash..


Example Usage

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

class counter
{
public:
    counter() : count(0) { }

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

private:
    boost::recursive_mutex mutex;
    int count;
};

counter c;

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

int main(int, char*[])
{
    const int num_threads=4;

    boost::thread_group threads;   
    for (int i=0; i < num_threads; ++i)
        threads.create_thread(&change_count, 0);
      
    threads.join_all();
   
    return 0;
}

The output is:

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

Revised 01 October, 2001

© Copyright William E. Kempf 2001 all rights reserved.