libs/thread/doc/mutexes.qbk

   1 [/
   2   (C) Copyright 2007-11 Anthony Williams
   3   (C) Copyright 2011-12 Vicente J. Botet Escriba
   4   Distributed under the Boost Software License, Version 1.0.
   5   (See accompanying file LICENSE_1_0.txt or copy at
   6   http://www.boost.org/LICENSE_1_0.txt).
   7 ]
   8
   9 [section:mutex_types Mutex Types]
  10
  11 [section:mutex Class `mutex`]
  12
  13     #include <boost/thread/mutex.hpp>
  14
  15     class mutex:
  16         boost::noncopyable
  17     {
  18     public:
  19         mutex();
  20         ~mutex();
  21
  22         void lock();
  23         bool try_lock();
  24         void unlock();
  25
  26         typedef platform-specific-type native_handle_type;
  27         native_handle_type native_handle();
  28
  29         typedef unique_lock<mutex> scoped_lock;
  30         typedef unspecified-type scoped_try_lock;
  31     };
  32
  33 __mutex__ implements the __lockable_concept__ to provide an exclusive-ownership mutex. At most one thread can own the lock on a given
  34 instance of __mutex__ at any time. Multiple concurrent calls to __lock_ref__, __try_lock_ref__ and __unlock_ref__ shall be permitted.
  35
  36 [section:nativehandle Member function `native_handle()`]
  37
  38     typedef platform-specific-type native_handle_type;
  39     native_handle_type native_handle();
  40
  41 [variablelist
  42
  43 [[Effects:] [Returns an instance of `native_handle_type` that can be used with platform-specific APIs to manipulate the underlying
  44 implementation. If no such instance exists, `native_handle()` and `native_handle_type` are not present.]]
  45
  46 [[Throws:] [Nothing.]]
  47
  48 ]
  49
  50 [endsect]
  51
  52
  53 [endsect]
  54
  55 [section:try_mutex Typedef `try_mutex`]
  56
  57     #include <boost/thread/mutex.hpp>
  58
  59     typedef mutex try_mutex;
  60
  61 __try_mutex__ is a `typedef` to __mutex__, provided for backwards compatibility with previous releases of boost.
  62
  63 [endsect]
  64
  65 [section:timed_mutex Class `timed_mutex`]
  66
  67     #include <boost/thread/mutex.hpp>
  68
  69     class timed_mutex:
  70         boost::noncopyable
  71     {
  72     public:
  73         timed_mutex();
  74         ~timed_mutex();
  75
  76         void lock();
  77         void unlock();
  78         bool try_lock();
  79
  80         template <class Rep, class Period>
  81         bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
  82         template <class Clock, class Duration>
  83         bool try_lock_until(const chrono::time_point<Clock, Duration>& t);
  84
  85         typedef platform-specific-type native_handle_type;
  86         native_handle_type native_handle();
  87
  88         typedef unique_lock<timed_mutex> scoped_timed_lock;
  89         typedef unspecified-type scoped_try_lock;
  90         typedef scoped_timed_lock scoped_lock;
  91
  92     #if defined BOOST_THREAD_PROVIDES_DATE_TIME || defined BOOST_THREAD_DONT_USE_CHRONO
  93         bool timed_lock(system_time const & abs_time);
  94         template<typename TimeDuration>
  95         bool timed_lock(TimeDuration const & relative_time);
  96     #endif
  97
  98     };
  99
 100 __timed_mutex__ implements the __timed_lockable_concept__ to provide an exclusive-ownership mutex. At most one thread can own the
 101 lock on a given instance of __timed_mutex__ at any time. Multiple concurrent calls to __lock_ref__, __try_lock_ref__,
 102 __timed_lock_ref__, __timed_lock_duration_ref__ and __unlock_ref__ shall be permitted.
 103
 104 [section:nativehandle Member function `native_handle()`]
 105
 106     typedef platform-specific-type native_handle_type;
 107     native_handle_type native_handle();
 108
 109 [variablelist
 110
 111 [[Effects:] [Returns an instance of `native_handle_type` that can be used with platform-specific APIs to manipulate the underlying
 112 implementation. If no such instance exists, `native_handle()` and `native_handle_type` are not present.]]
 113
 114 [[Throws:] [Nothing.]]
 115
 116 ]
 117
 118 [endsect]
 119
 120 [endsect]
 121
 122 [section:recursive_mutex Class `recursive_mutex`]
 123
 124     #include <boost/thread/recursive_mutex.hpp>
 125
 126     class recursive_mutex:
 127         boost::noncopyable
 128     {
 129     public:
 130         recursive_mutex();
 131         ~recursive_mutex();
 132
 133         void lock();
 134         bool try_lock() noexcept;
 135         void unlock();
 136
 137         typedef platform-specific-type native_handle_type;
 138         native_handle_type native_handle();
 139
 140         typedef unique_lock<recursive_mutex> scoped_lock;
 141         typedef unspecified-type scoped_try_lock;
 142     };
 143
 144 __recursive_mutex__ implements the __lockable_concept__ to provide an exclusive-ownership recursive mutex. At most one thread can
 145 own the lock on a given instance of __recursive_mutex__ at any time. Multiple concurrent calls to __lock_ref__, __try_lock_ref__ and
 146 __unlock_ref__ shall be permitted. A thread that already has exclusive ownership of a given __recursive_mutex__ instance can call
 147 __lock_ref__ or __try_lock_ref__ to acquire an additional level of ownership of the mutex. __unlock_ref__ must be called once for
 148 each level of ownership acquired by a single thread before ownership can be acquired by another thread.
 149
 150 [section:nativehandle Member function `native_handle()`]
 151
 152     typedef platform-specific-type native_handle_type;
 153     native_handle_type native_handle();
 154
 155 [variablelist
 156
 157 [[Effects:] [Returns an instance of `native_handle_type` that can be used with platform-specific APIs to manipulate the underlying
 158 implementation. If no such instance exists, `native_handle()` and `native_handle_type` are not present.]]
 159
 160 [[Throws:] [Nothing.]]
 161
 162 ]
 163
 164 [endsect]
 165
 166 [endsect]
 167
 168 [section:recursive_try_mutex Typedef `recursive_try_mutex`]
 169
 170     #include <boost/thread/recursive_mutex.hpp>
 171
 172     typedef recursive_mutex recursive_try_mutex;
 173
 174 __recursive_try_mutex__ is a `typedef` to __recursive_mutex__, provided for backwards compatibility with previous releases of boost.
 175
 176 [endsect]
 177
 178 [section:recursive_timed_mutex Class `recursive_timed_mutex`]
 179
 180     #include <boost/thread/recursive_mutex.hpp>
 181
 182     class recursive_timed_mutex:
 183         boost::noncopyable
 184     {
 185     public:
 186         recursive_timed_mutex();
 187         ~recursive_timed_mutex();
 188
 189         void lock();
 190         bool try_lock() noexcept;
 191         void unlock();
 192
 193
 194         template <class Rep, class Period>
 195         bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
 196         template <class Clock, class Duration>
 197         bool try_lock_until(const chrono::time_point<Clock, Duration>& t);
 198
 199         typedef platform-specific-type native_handle_type;
 200         native_handle_type native_handle();
 201
 202         typedef unique_lock<recursive_timed_mutex> scoped_lock;
 203         typedef unspecified-type scoped_try_lock;
 204         typedef scoped_lock scoped_timed_lock;
 205
 206     #if defined BOOST_THREAD_PROVIDES_DATE_TIME || defined BOOST_THREAD_DONT_USE_CHRONO
 207         bool timed_lock(system_time const & abs_time);
 208         template<typename TimeDuration>
 209         bool timed_lock(TimeDuration const & relative_time);
 210     #endif
 211
 212     };
 213
 214 __recursive_timed_mutex__ implements the __timed_lockable_concept__ to provide an exclusive-ownership recursive mutex. At most one
 215 thread can own the lock on a given instance of __recursive_timed_mutex__ at any time. Multiple concurrent calls to __lock_ref__,
 216 __try_lock_ref__, __timed_lock_ref__, __timed_lock_duration_ref__ and __unlock_ref__ shall be permitted. A thread that already has
 217 exclusive ownership of a given __recursive_timed_mutex__ instance can call __lock_ref__, __timed_lock_ref__,
 218 __timed_lock_duration_ref__ or __try_lock_ref__ to acquire an additional level of ownership of the mutex. __unlock_ref__ must be
 219 called once for each level of ownership acquired by a single thread before ownership can be acquired by another thread.
 220
 221 [section:nativehandle Member function `native_handle()`]
 222
 223     typedef platform-specific-type native_handle_type;
 224     native_handle_type native_handle();
 225
 226 [variablelist
 227
 228 [[Effects:] [Returns an instance of `native_handle_type` that can be used with platform-specific APIs to manipulate the underlying
 229 implementation. If no such instance exists, `native_handle()` and `native_handle_type` are not present.]]
 230
 231 [[Throws:] [Nothing.]]
 232
 233 ]
 234
 235 [endsect]
 236
 237 [endsect]
 238
 239 [include shared_mutex_ref.qbk]
 240
 241 [endsect]
 242
 243
 244