thread/doc/shared_mutex_ref.qbk

[/
  (C) Copyright 2007-8 Anthony Williams.
  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]

[section:shared_mutex Class `shared_mutex`]

    #include <boost/thread/shared_mutex.hpp>

    class shared_mutex
    {
    public:
        shared_mutex(shared_mutex const&) = delete;
        shared_mutex& operator=(shared_mutex const&) = delete;

        shared_mutex();
        ~shared_mutex();

        void lock_shared();
        bool try_lock_shared();
        template <class Rep, class Period>
        bool try_lock_shared_for(const chrono::duration<Rep, Period>& rel_time);
        template <class Clock, class Duration>
        bool try_lock_shared_until(const chrono::time_point<Clock, Duration>& abs_time);
        void unlock_shared();

        void lock();
        bool try_lock();
        template <class Rep, class Period>
        bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
        template <class Clock, class Duration>
        bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
        void unlock();

    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0
        // use upgrade_mutex instead.
        void lock_upgrade();
        void unlock_upgrade();

        void unlock_upgrade_and_lock();
        void unlock_and_lock_upgrade();
        void unlock_and_lock_shared();
        void unlock_upgrade_and_lock_shared();
    #endif

    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
        bool timed_lock_shared(system_time const& timeout);
        bool timed_lock(system_time const& timeout);
    #endif

    };

The class `boost::shared_mutex` provides an implementation of a multiple-reader / single-writer mutex. It implements the
__shared_lockable_concept__.

Multiple concurrent calls to __lock_ref__, __try_lock_ref__, `__try_lock_for()`,  `__try_lock_until()`, __timed_lock_ref__, __lock_shared_ref__,  
`__try_lock_shared_for()`,  `__try_lock_shared_until()`, __try_lock_shared_ref__ and __timed_lock_shared_ref__ are permitted.


[endsect]

[section:upgrade_mutex Class `upgrade_mutex`]

    #include <boost/thread/shared_mutex.hpp>

    class upgrade_mutex
    {
    public:
        upgrade_mutex(upgrade_mutex const&) = delete;
        upgrade_mutex& operator=(upgrade_mutex const&) = delete;

        upgrade_mutex();
        ~upgrade_mutex();

        void lock_shared();
        bool try_lock_shared();
        template <class Rep, class Period>
        bool try_lock_shared_for(const chrono::duration<Rep, Period>& rel_time);
        template <class Clock, class Duration>
        bool try_lock_shared_until(const chrono::time_point<Clock, Duration>& abs_time);
        void unlock_shared();

        void lock();
        bool try_lock();
        template <class Rep, class Period>
        bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
        template <class Clock, class Duration>
        bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
        void unlock();

        void lock_upgrade();
        template <class Rep, class Period>
        bool try_lock_upgrade_for(const chrono::duration<Rep, Period>& rel_time);
        template <class Clock, class Duration>
        bool try_lock_upgrade_until(const chrono::time_point<Clock, Duration>& abs_time);
        void unlock_upgrade();

        // Shared <-> Exclusive

    #ifdef BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSIONS
        bool try_unlock_shared_and_lock();
        template <class Rep, class Period>
        bool try_unlock_shared_and_lock_for(const chrono::duration<Rep, Period>& rel_time);
        template <class Clock, class Duration>
        bool try_unlock_shared_and_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
    #endif
        void unlock_and_lock_shared();

        // Shared <-> Upgrade

    #ifdef BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSIONS
        bool try_unlock_shared_and_lock_upgrade();
        template <class Rep, class Period>
        bool try_unlock_shared_and_lock_upgrade_for(const chrono::duration<Rep, Period>& rel_time);
        template <class Clock, class Duration>
        bool try_unlock_shared_and_lock_upgrade_until(const chrono::time_point<Clock, Duration>& abs_time);
    #endif
        void unlock_upgrade_and_lock_shared();

        // Upgrade <-> Exclusive

        void unlock_upgrade_and_lock();
    #if    defined(BOOST_THREAD_PLATFORM_PTHREAD)
        || defined(BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN)
        bool try_unlock_upgrade_and_lock();
        template <class Rep, class Period>
        bool try_unlock_upgrade_and_lock_for(const chrono::duration<Rep, Period>& rel_time);
        template <class Clock, class Duration>
        bool try_unlock_upgrade_and_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
    #endif
        void unlock_and_lock_upgrade();
    };

The class `boost::upgrade_mutex` provides an implementation of a multiple-reader / single-writer mutex. It implements the
__upgrade_lockable_concept__.

Multiple concurrent calls to __lock_ref__, __try_lock_ref__, `__try_lock_for()`,  `__try_lock_until()`, __timed_lock_ref__, __lock_shared_ref__,  
`__try_lock_shared_for()`,  `__try_lock_shared_until()`, __try_lock_shared_ref__ and __timed_lock_shared_ref__ are permitted.


[endsect]