[ceph.git] / ceph / src / boost / libs / 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` -- C++14]

    #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(); // EXTENSION
        void unlock_upgrade(); // EXTENSION

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

    #if defined BOOST_THREAD_USES_DATETIME
        bool timed_lock_shared(system_time const& timeout); // DEPRECATED
        bool timed_lock(system_time const& timeout); // DEPRECATED
    #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.

Note the the lack of reader-writer priority policies in shared_mutex. This is due to an algorithm credited to Alexander Terekhov which lets the OS decide which thread is the next to get the lock without caring whether a unique lock or shared lock is being sought. This results in a complete lack of reader or writer starvation. It is simply fair. 

[endsect]

[section:upgrade_mutex Class `upgrade_mutex` -- EXTENSION]

    #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]

[section:null_mutex Class `null_mutex` -- EXTENSION]

    #include <boost/thread/null_mutex.hpp>

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

        null_mutex();
        ~null_mutex();

        void lock_shared();
        bool try_lock_shared();
     #ifdef BOOST_THREAD_USES_CHRONO
        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);
     #endif
        void unlock_shared();

        void lock();
        bool try_lock();
     #ifdef BOOST_THREAD_USES_CHRONO
        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);
     #endif
        void unlock();

        void lock_upgrade();
     #ifdef BOOST_THREAD_USES_CHRONO
        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);
     #endif
        void unlock_upgrade();

        // Shared <-> Exclusive

        bool try_unlock_shared_and_lock();
     #ifdef BOOST_THREAD_USES_CHRONO
        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

        bool try_unlock_shared_and_lock_upgrade();
     #ifdef BOOST_THREAD_USES_CHRONO
        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();
        bool try_unlock_upgrade_and_lock();
     #ifdef BOOST_THREAD_USES_CHRONO
        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::null_mutex` provides a no-op implementation of a multiple-reader / single-writer mutex. It is a model of the
__UpgradeLockable concept.


[endsect]
Commit	Line	Data
7c673cae FG	1	[/
	2	(C) Copyright 2007-8 Anthony Williams.
	3	Distributed under the Boost Software License, Version 1.0.
	4	(See accompanying file LICENSE_1_0.txt or copy at
	5	http://www.boost.org/LICENSE_1_0.txt).
	6	]
	7
	8	[section:shared_mutex Class `shared_mutex` -- C++14]
	9
	10	#include <boost/thread/shared_mutex.hpp>
	11
	12	class shared_mutex
	13	{
	14	public:
	15	shared_mutex(shared_mutex const&) = delete;
	16	shared_mutex& operator=(shared_mutex const&) = delete;
	17
	18	shared_mutex();
	19	~shared_mutex();
	20
	21	void lock_shared();
	22	bool try_lock_shared();
	23	template <class Rep, class Period>
	24	bool try_lock_shared_for(const chrono::duration<Rep, Period>& rel_time);
	25	template <class Clock, class Duration>
	26	bool try_lock_shared_until(const chrono::time_point<Clock, Duration>& abs_time);
	27	void unlock_shared();
	28
	29	void lock();
	30	bool try_lock();
	31	template <class Rep, class Period>
	32	bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
	33	template <class Clock, class Duration>
	34	bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
	35	void unlock();
	36
	37	#if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0
	38	// use upgrade_mutex instead.
	39	void lock_upgrade(); // EXTENSION
	40	void unlock_upgrade(); // EXTENSION
	41
	42	void unlock_upgrade_and_lock(); // EXTENSION
	43	void unlock_and_lock_upgrade(); // EXTENSION
	44	void unlock_and_lock_shared(); // EXTENSION
	45	void unlock_upgrade_and_lock_shared(); // EXTENSION
	46	#endif
	47
	48	#if defined BOOST_THREAD_USES_DATETIME
	49	bool timed_lock_shared(system_time const& timeout); // DEPRECATED
	50	bool timed_lock(system_time const& timeout); // DEPRECATED
	51	#endif
	52
	53	};
	54
	55	The class `boost::shared_mutex` provides an implementation of a multiple-reader / single-writer mutex. It implements the
	56	__shared_lockable_concept__.
	57
	58	Multiple concurrent calls to __lock_ref__, __try_lock_ref__, `__try_lock_for()`, `__try_lock_until()`, __timed_lock_ref__, __lock_shared_ref__,
	59	`__try_lock_shared_for()`, `__try_lock_shared_until()`, __try_lock_shared_ref__ and __timed_lock_shared_ref__ are permitted.
	60
	61	Note the the lack of reader-writer priority policies in shared_mutex. This is due to an algorithm credited to Alexander Terekhov which lets the OS decide which thread is the next to get the lock without caring whether a unique lock or shared lock is being sought. This results in a complete lack of reader or writer starvation. It is simply fair.
	62
	63	[endsect]
	64
65	[section:upgrade_mutex Class `upgrade_mutex` -- EXTENSION]
66
67	#include <boost/thread/shared_mutex.hpp>
68
69	class upgrade_mutex
70	{
71	public:
72	upgrade_mutex(upgrade_mutex const&) = delete;
73	upgrade_mutex& operator=(upgrade_mutex const&) = delete;
74
75	upgrade_mutex();
76	~upgrade_mutex();
77
78	void lock_shared();
79	bool try_lock_shared();
80	template <class Rep, class Period>
81	bool try_lock_shared_for(const chrono::duration<Rep, Period>& rel_time);
82	template <class Clock, class Duration>
83	bool try_lock_shared_until(const chrono::time_point<Clock, Duration>& abs_time);
84	void unlock_shared();
85
86	void lock();
87	bool try_lock();
88	template <class Rep, class Period>
89	bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
90	template <class Clock, class Duration>
91	bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
92	void unlock();
93
94	void lock_upgrade();
95	template <class Rep, class Period>
96	bool try_lock_upgrade_for(const chrono::duration<Rep, Period>& rel_time);
97	template <class Clock, class Duration>
98	bool try_lock_upgrade_until(const chrono::time_point<Clock, Duration>& abs_time);
99	void unlock_upgrade();
100
101	// Shared <-> Exclusive
102
103	#ifdef BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSIONS
104	bool try_unlock_shared_and_lock();
105	template <class Rep, class Period>
106	bool try_unlock_shared_and_lock_for(const chrono::duration<Rep, Period>& rel_time);
107	template <class Clock, class Duration>
108	bool try_unlock_shared_and_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
109	#endif
110	void unlock_and_lock_shared();
111
112	// Shared <-> Upgrade
113
114	#ifdef BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSIONS
115	bool try_unlock_shared_and_lock_upgrade();
116	template <class Rep, class Period>
117	bool try_unlock_shared_and_lock_upgrade_for(const chrono::duration<Rep, Period>& rel_time);
118	template <class Clock, class Duration>
119	bool try_unlock_shared_and_lock_upgrade_until(const chrono::time_point<Clock, Duration>& abs_time);
120	#endif
121	void unlock_upgrade_and_lock_shared();
122
123	// Upgrade <-> Exclusive
124
125	void unlock_upgrade_and_lock();
126	#if defined(BOOST_THREAD_PLATFORM_PTHREAD)
127	\|\| defined(BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN)
128	bool try_unlock_upgrade_and_lock();
129	template <class Rep, class Period>
130	bool try_unlock_upgrade_and_lock_for(const chrono::duration<Rep, Period>& rel_time);
131	template <class Clock, class Duration>
132	bool try_unlock_upgrade_and_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
133	#endif
134	void unlock_and_lock_upgrade();
135	};
136
137	The class `boost::upgrade_mutex` provides an implementation of a multiple-reader / single-writer mutex. It implements the
138	__upgrade_lockable_concept__.
139
140	Multiple concurrent calls to __lock_ref__, __try_lock_ref__, `__try_lock_for()`, `__try_lock_until()`, __timed_lock_ref__, __lock_shared_ref__,
141	`__try_lock_shared_for()`, `__try_lock_shared_until()`, __try_lock_shared_ref__ and __timed_lock_shared_ref__ are permitted.
142
143
144	[endsect]
145
146	[section:null_mutex Class `null_mutex` -- EXTENSION]
147
148	#include <boost/thread/null_mutex.hpp>
149
150	class null_mutex
151	{
152	public:
153	null_mutex(null_mutex const&) = delete;
154	null_mutex& operator=(null_mutex const&) = delete;
155
156	null_mutex();
157	~null_mutex();
158
159	void lock_shared();
160	bool try_lock_shared();
161	#ifdef BOOST_THREAD_USES_CHRONO
162	template <class Rep, class Period>
163	bool try_lock_shared_for(const chrono::duration<Rep, Period>& rel_time);
164	template <class Clock, class Duration>
165	bool try_lock_shared_until(const chrono::time_point<Clock, Duration>& abs_time);
166	#endif
167	void unlock_shared();
168
169	void lock();
170	bool try_lock();
171	#ifdef BOOST_THREAD_USES_CHRONO
172	template <class Rep, class Period>
173	bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
174	template <class Clock, class Duration>
175	bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
176	#endif
177	void unlock();
178
179	void lock_upgrade();
180	#ifdef BOOST_THREAD_USES_CHRONO
181	template <class Rep, class Period>
182	bool try_lock_upgrade_for(const chrono::duration<Rep, Period>& rel_time);
183	template <class Clock, class Duration>
184	bool try_lock_upgrade_until(const chrono::time_point<Clock, Duration>& abs_time);
185	#endif
186	void unlock_upgrade();
187
188	// Shared <-> Exclusive
189
190	bool try_unlock_shared_and_lock();
191	#ifdef BOOST_THREAD_USES_CHRONO
192	template <class Rep, class Period>
193	bool try_unlock_shared_and_lock_for(const chrono::duration<Rep, Period>& rel_time);
194	template <class Clock, class Duration>
195	bool try_unlock_shared_and_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
196	#endif
197	void unlock_and_lock_shared();
198
199	// Shared <-> Upgrade
200
201	bool try_unlock_shared_and_lock_upgrade();
202	#ifdef BOOST_THREAD_USES_CHRONO
203	template <class Rep, class Period>
204	bool try_unlock_shared_and_lock_upgrade_for(const chrono::duration<Rep, Period>& rel_time);
205	template <class Clock, class Duration>
206	bool try_unlock_shared_and_lock_upgrade_until(const chrono::time_point<Clock, Duration>& abs_time);
207	#endif
208	void unlock_upgrade_and_lock_shared();
209
210	// Upgrade <-> Exclusive
211
212	void unlock_upgrade_and_lock();
213	bool try_unlock_upgrade_and_lock();
214	#ifdef BOOST_THREAD_USES_CHRONO
215	template <class Rep, class Period>
216	bool try_unlock_upgrade_and_lock_for(const chrono::duration<Rep, Period>& rel_time);
217	template <class Clock, class Duration>
218	bool try_unlock_upgrade_and_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
219	#endif
220	void unlock_and_lock_upgrade();
221	};
222
223	The class `boost::null_mutex` provides a no-op implementation of a multiple-reader / single-writer mutex. It is a model of the
224	__UpgradeLockable concept.
225
226
227	[endsect]
228