C++ Boost

Boost.Threads

mutex
try_mutex
timed_mutex


Introduction
Header
Class mutex Synopsis
Class mutex Members
Class try_mutex Synopsis
Class try_mutex Members
Class timed_mutex Synopsis
Class timed_mutex Members
Example

Introduction

The mutex, try_mutex and timed_mutex classes define full featured models of the Mutex, TryMutex, and TimedMutex concepts. These types should be used to non-recursively synchronize access to shared resources. For recursive locking mechanics, see recursive 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
mutex scoped_lock boost::detail::thread::scoped_lock<mutex> ScopedLock
try_mutex scoped_lock
scoped_try_lock
boost::detail::thread::scoped_lock<try_mutex>
boost::detail::thread::scoped_try_lock<try_mutex>
ScopedLock
ScopedTryLock
timed_mutex scoped_lock
scoped_try_lock
scoped_timed_lock
boost::detail::thread::scoped_lock<timed_mutex>
boost::detail::thread::scoped_try_lock<timed_mutex>
boost::detail::thread::scoped_timed_lock<timed_mutex>
ScopedLock
ScopedTryLock
ScopedTimedLock

The mutex, try_mutex and timed_mutex classes use an Unspecified locking strategy, so attempts to recursively lock them or attempts to unlock them by threads that don't own a lock on them result in undefined behavior. This strategy allows implementations to be as efficient as possible on any given platform. It is, however, recommended that implementations include debugging support to detect misuse when NDEBUG is not defined.

Like all the Boost.Threads mutex models, the mutex, try_mutex and 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/mutex.hpp>

Class mutex Synopsis

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

Class mutex Members


Constructor

    mutex();

Postconditions: *this is in the unlocked state.


Destructor

    ~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 try_mutex Synopsis

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

Class try_mutex Members


Constructor

    try_mutex();

Postconditions: *this is in the unlocked state.


Destructor

    ~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 timed_mutex Synopsis

namespace boost
{
    class timed_mutex : private boost::noncopyable // Exposition only.
        // Class 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;
        
        timed_mutex();
        ~timed_mutex();
    };
}

Class timed_mutex Members


Constructor

    timed_mutex();

Postconditions: *this is in the unlocked state.


Destructor

    ~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/mutex.hpp>
#include <boost/thread/thread.hpp>
#include <iostream>

boost::mutex io_mutex; // The iostreams are not guaranteed to be thread-safe!

class counter
{
public:
    counter() : count(0) { }
   
    int increment() {
        boost::mutex::scoped_lock scoped_lock(mutex);
        return ++count;
    }

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

counter c;

void change_count(void*)
{
    int i = c.increment();
    boost::mutex::scoped_lock scoped_lock(io_mutex);
    std::cout << "count == " << i << std::endl;
}

int main(int, char*[])
{
    const int num_threads = 4;
    boost::thread_group thrds;
    for (int i=0; i < num_threads; ++i)
        thrds.create_thread(&change_count, 0);
      
    thrds.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.