Boost.Threads

Header <boost/thread/rw_mutex.hpp>

Introduction

The rw_mutex, try_rw_mutex and timed_rw_mutex classes define full featured models of the RWMutex, TryRWMutex, and TimedRWMutex concepts. These types should be used to synchronize access to shared resources. Recursive or non-recursive locking mechanics are acheived by supplying the appropriate Mutex type as a parameter.

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

rw_mutex Class	Lock name	Implementation defined Lock Type	Lock Concept
`rw_mutex`	`scoped_rw_lock`	`boost::detail::thread::scoped_rw_lock<rw_mutex>`	ScopedRWLock
`try_rw_mutex`	`scoped_rw_lock scoped_try_rw_lock`	`boost::detail::thread::scoped_rw_lock<try_rw_mutex>` `boost::detail::thread::scoped_try_rw_lock<try_rw_mutex>`	ScopedRWLock ScopedRWTryLock
`timed_rw_mutex`	`scoped_rw_lock scoped_try_rw_lock scoped_timed_rw_lock`	`boost::detail::thread::scoped_rw_lock<timed_rw_mutex>` `boost::detail::thread::scoped_try_rw_lock<timed_rw_mutex>boost::detail::thread::scoped_timed_rw_lock<timed_rw_mutex>`	ScopedRWLock ScopedRWTryLock ScopedRWTimedLock

The rw_mutex, try_rw_mutex and timed_rw_mutex classes leave the locking strategy as Unspecified. Programmers should assume that threads that lock a rw_mutex, try_rw_mutex, or timed_rw_mutex multiple times will deadlock, unless all of the lock requests are for read-locks.

The rw_mutex, try_rw_mutex and timed_rw_mutex allow the programmer to explicitly choose the scheduling policy for the lock. This scheduling policy will dictate how competing readers and writers will acquire the lock. It does not, however, dictate the order that individual read or write requests will be granted, in comparison to other requests of the same type. 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.

Release Notes/Caveats

Self-deadlock is virtually guaranteed if a thread tries to lock the same rw_mutex multiple times, unless all locks are read-locks (but see below)
This implementation does not protect against reader overflow. If more than INT_MAX readers obtain or try to obtain a lock simultaneously, the behavior is undefined. This will be addressed in a future release, but it seems that detecting this condition & reporting an error or throwing an exception should suffice for realistic uses. Having readers beyond INT_MAX wait for the count to decrease only pushes the overflow problem onto another variable... Suggestions?
See the comments at the head of rw_mutex.cpp for a description of the implementation itself.

Macros

Values

namespace boost {
    typedef enum 
    { 
        sp_writer_priority, 
        sp_reader_priority, 
        sp_alternating_many_reads, 
        sp_alternating_single_reads 
    } rw_scheduling_policy;
    
    typedef enum 
    {
        NO_LOCK,
        SHARED_LOCK,
        EXCL_LOCK
    } lockstate; 
}

Types

Classes

Class `rw_mutex`

Class `rw_mutex` synopsis

namespace boost
{
    class rw_mutex : private boost::noncopyable // Exposition only.
        // Class mutex meets the NonCopyable requirement.
    { 
    public:
        typedef [implementation defined; see Introduction] scoped_rw_lock;

        rw_mutex(rw_scheduling_policy sp=sp_writer_priority);
        ~rw_mutex();
    };
};

Class `rw_mutex` constructors and destructor

rw_mutex(rw_scheduling_policy sp=sp_writer_priority);

Postconditions: *this is in the NO_LOCK state.

~rw_mutex();

Requires: *this is in the NO_LOCK state.
Effects: Destroys *this.
Danger: Destruction of a locked rw_mutex is a serious programming error resulting in undefined behavior such as a program crash.

Class `rw_try_mutex`

Class `rw_try_mutex` synopsis

namespace boost
{
    class rw_mutex : private boost::noncopyable // Exposition only.
        // Class mutex meets the NonCopyable requirement.
    { 
    public:
        typedef [implementation defined; see Introduction] scoped_rw_lock;
        typedef [implementation defined; see Introduction] scoped_rw_try_lock;

        rw_try_mutex(rw_scheduling_policy sp=sp_writer_priority);
        ~rw_try_mutex();
    };
};

Class `rw_try_mutex` constructors and destructor

rw_try_mutex(rw_scheduling_policy sp=sp_writer_priority);

Postconditions: *this is in the NO_LOCK state.

~rw_try_mutex();

Requires: *this is in the NO_LOCK state.
Effects: Destroys *this.
Danger: Destruction of a locked rw_mutex is a serious programming error resulting in undefined behavior such as a program crash.

Class `rw_timed_mutex`

Class `rw_timed_mutex` synopsis

namespace boost
{
    class rw_timed_mutex : private boost::noncopyable // Exposition only.
        // Class mutex meets the NonCopyable requirement.
    { 
    public:
        typedef [implementation defined; see Introduction] scoped_rw_lock;
        typedef [implementation defined; see Introduction] scoped_rw_try_lock;
        typedef [implementation defined; see Introduction] scoped_rw_timed_lock;

        rw_timed_mutex(rw_scheduling_policy sp=sp_writer_priority);
        ~rw_timed_mutex();
    };
};

Class `rw_timed_mutex` constructors and destructor

rw_timed_mutex(rw_scheduling_policy sp=sp_writer_priority);

Postconditions: *this is in the NO_LOCK state.

~rw_timed_mutex();

Requires: *this is in the NO_LOCK state.
Effects: Destroys *this.
Danger: Destruction of a locked rw_mutex is a serious programming error resulting in undefined behavior such as a program crash.

Example(s)

#include <boost/thread/rw_mutex.hpp>
#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::rw_mutex::scoped_lock scoped_rw_lock(rw_mutex);
        return ++count;
    }

    int get() {
        boost::rw_mutex::scoped_lock scoped_rw_lock(rw_mutex,SHARED_LOCK);
	return count;
    }
        
private:
    boost::rw_mutex rwm(boost::sp_writer_priority);
    int count;
};

counter c;

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

void get_count(void*)
{
    int i = c.get();
    boost::rw_mutex::scoped_lock scoped_lock(io_mutex);
    std::cout << "get_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.create_thread(&get_count,0);
    }
      
    thrds.join_all();
   
    return 0;
}

Typicial output might be:

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

Of course, exact output is platform dependent since the locking behavior with competing readers and writers is undefined.

Revised 05 November, 2001

Boost.Threads

Header <boost/thread/rw_mutex.hpp>

Contents

Introduction

Release Notes/Caveats

Macros

Values

Types

Classes

Class rw_mutex

Class rw_mutex synopsis

Class rw_mutex constructors and destructor

Class rw_try_mutex

Class rw_try_mutex synopsis

Class rw_try_mutex constructors and destructor

Class rw_timed_mutex

Class rw_timed_mutex synopsis

Class rw_timed_mutex constructors and destructor