# Boost.Threads, recursive_mutex
Keywords: threads, BTL, thread library, C++

###

# 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 05 November, 2001

© Copyright William E. Kempf 2001 all rights reserved.