• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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
55The class `boost::shared_mutex` provides an implementation of a multiple-reader / single-writer mutex. It implements the
56__shared_lockable_concept__.
57
58Multiple 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
61Note 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
137The class `boost::upgrade_mutex` provides an implementation of a multiple-reader / single-writer mutex. It implements the
138__upgrade_lockable_concept__.
139
140Multiple 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
223The 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
229