libstdc++
std_mutex.h
Go to the documentation of this file.
1 // std::mutex implementation -*- C++ -*-
2 
3 // Copyright (C) 2003-2025 Free Software Foundation, Inc.
4 //
5 // This file is part of the GNU ISO C++ Library. This library is free
6 // software; you can redistribute it and/or modify it under the
7 // terms of the GNU General Public License as published by the
8 // Free Software Foundation; either version 3, or (at your option)
9 // any later version.
10 
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 // GNU General Public License for more details.
15 
16 // Under Section 7 of GPL version 3, you are granted additional
17 // permissions described in the GCC Runtime Library Exception, version
18 // 3.1, as published by the Free Software Foundation.
19 
20 // You should have received a copy of the GNU General Public License and
21 // a copy of the GCC Runtime Library Exception along with this program;
22 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23 // <http://www.gnu.org/licenses/>.
24 
25 /** @file bits/std_mutex.h
26  * This is an internal header file, included by other library headers.
27  * Do not attempt to use it directly. @headername{mutex}
28  */
29 
30 #ifndef _GLIBCXX_MUTEX_H
31 #define _GLIBCXX_MUTEX_H 1
32 
33 #ifdef _GLIBCXX_SYSHDR
34 #pragma GCC system_header
35 #endif
36 
37 #if __cplusplus < 201103L
38 # include <bits/c++0x_warning.h>
39 #else
40 
41 #include <errno.h> // EBUSY
42 #include <bits/functexcept.h>
43 #include <bits/gthr.h>
44 
45 namespace std _GLIBCXX_VISIBILITY(default)
46 {
47 _GLIBCXX_BEGIN_NAMESPACE_VERSION
48 
49  /**
50  * @defgroup mutexes Mutexes
51  * @ingroup concurrency
52  *
53  * Classes for mutex support.
54  * @{
55  */
56 
57 #ifdef _GLIBCXX_HAS_GTHREADS
58  /// @cond undocumented
59 
60  // Common base class for std::mutex and std::timed_mutex
61  class __mutex_base
62  {
63  protected:
64  typedef __gthread_mutex_t __native_type;
65 
66 #ifdef __GTHREAD_MUTEX_INIT
67  __native_type _M_mutex = __GTHREAD_MUTEX_INIT;
68 
69  constexpr __mutex_base() noexcept = default;
70 #else
71  __native_type _M_mutex;
72 
73  __mutex_base() noexcept
74  {
75  // XXX EAGAIN, ENOMEM, EPERM, EBUSY(may), EINVAL(may)
76  __GTHREAD_MUTEX_INIT_FUNCTION(&_M_mutex);
77  }
78 
79  ~__mutex_base() noexcept { __gthread_mutex_destroy(&_M_mutex); }
80 #endif
81 
82  __mutex_base(const __mutex_base&) = delete;
83  __mutex_base& operator=(const __mutex_base&) = delete;
84  };
85  /// @endcond
86 
87  /** The standard mutex type.
88  *
89  * A simple, non-recursive, non-timed mutex.
90  *
91  * Do not call `lock()` and `unlock()` directly, use a scoped lock type
92  * such as `std::unique_lock`, `std::lock_guard`, or (since C++17)
93  * `std::scoped_lock`.
94  *
95  * @headerfile mutex
96  * @since C++11
97  */
98  class mutex : private __mutex_base
99  {
100  public:
101  typedef __native_type* native_handle_type;
102 
103 #ifdef __GTHREAD_MUTEX_INIT
104  constexpr
105 #endif
106  mutex() noexcept = default;
107  ~mutex() = default;
108 
109  mutex(const mutex&) = delete;
110  mutex& operator=(const mutex&) = delete;
111 
112  void
113  lock()
114  {
115  int __e = __gthread_mutex_lock(&_M_mutex);
116 
117  // EINVAL, EAGAIN, EBUSY, EINVAL, EDEADLK(may)
118  if (__e)
119  __throw_system_error(__e);
120  }
121 
122  _GLIBCXX_NODISCARD
123  bool
124  try_lock() noexcept
125  {
126  // XXX EINVAL, EAGAIN, EBUSY
127  return !__gthread_mutex_trylock(&_M_mutex);
128  }
129 
130  void
131  unlock()
132  {
133  // XXX EINVAL, EAGAIN, EPERM
134  __gthread_mutex_unlock(&_M_mutex);
135  }
136 
137  native_handle_type
138  native_handle() noexcept
139  { return &_M_mutex; }
140  };
141 
142  /// @cond undocumented
143 
144  // Implementation details for std::condition_variable
145  class __condvar
146  {
147  using timespec = __gthread_time_t;
148 
149  public:
150  __condvar() noexcept
151  {
152 #ifndef __GTHREAD_COND_INIT
153  __GTHREAD_COND_INIT_FUNCTION(&_M_cond);
154 #endif
155  }
156 
157  ~__condvar()
158  {
159  int __e __attribute__((__unused__)) = __gthread_cond_destroy(&_M_cond);
160  __glibcxx_assert(__e != EBUSY); // threads are still blocked
161  }
162 
163  __condvar(const __condvar&) = delete;
164  __condvar& operator=(const __condvar&) = delete;
165 
166  __gthread_cond_t* native_handle() noexcept { return &_M_cond; }
167 
168  // Expects: Calling thread has locked __m.
169  void
170  wait(mutex& __m)
171  {
172  int __e __attribute__((__unused__))
173  = __gthread_cond_wait(&_M_cond, __m.native_handle());
174  __glibcxx_assert(__e == 0);
175  }
176 
177  void
178  wait_until(mutex& __m, timespec& __abs_time)
179  {
180  __gthread_cond_timedwait(&_M_cond, __m.native_handle(), &__abs_time);
181  }
182 
183 #ifdef _GLIBCXX_USE_PTHREAD_COND_CLOCKWAIT
184  void
185  wait_until(mutex& __m, clockid_t __clock, timespec& __abs_time)
186  {
187  pthread_cond_clockwait(&_M_cond, __m.native_handle(), __clock,
188  &__abs_time);
189  }
190 #endif
191 
192  void
193  notify_one() noexcept
194  {
195  int __e __attribute__((__unused__)) = __gthread_cond_signal(&_M_cond);
196  __glibcxx_assert(__e == 0);
197  }
198 
199  void
200  notify_all() noexcept
201  {
202  int __e __attribute__((__unused__)) = __gthread_cond_broadcast(&_M_cond);
203  __glibcxx_assert(__e == 0);
204  }
205 
206  protected:
207 #ifdef __GTHREAD_COND_INIT
208  __gthread_cond_t _M_cond = __GTHREAD_COND_INIT;
209 #else
210  __gthread_cond_t _M_cond;
211 #endif
212  };
213  /// @endcond
214 
215 #endif // _GLIBCXX_HAS_GTHREADS
216 
217  /// Do not acquire ownership of the mutex.
218  struct defer_lock_t { explicit defer_lock_t() = default; };
219 
220  /// Try to acquire ownership of the mutex without blocking.
221  struct try_to_lock_t { explicit try_to_lock_t() = default; };
222 
223  /// Assume the calling thread has already obtained mutex ownership
224  /// and manage it.
225  struct adopt_lock_t { explicit adopt_lock_t() = default; };
226 
227  /// Tag used to prevent a scoped lock from acquiring ownership of a mutex.
228  _GLIBCXX17_INLINE constexpr defer_lock_t defer_lock { };
229 
230  /// Tag used to prevent a scoped lock from blocking if a mutex is locked.
231  _GLIBCXX17_INLINE constexpr try_to_lock_t try_to_lock { };
232 
233  /// Tag used to make a scoped lock take ownership of a locked mutex.
234  _GLIBCXX17_INLINE constexpr adopt_lock_t adopt_lock { };
235 
236  /** @brief A simple scoped lock type.
237  *
238  * A lock_guard controls mutex ownership within a scope, releasing
239  * ownership in the destructor.
240  *
241  * @headerfile mutex
242  * @since C++11
243  */
244  template<typename _Mutex>
246  {
247  public:
248  typedef _Mutex mutex_type;
249 
250  [[__nodiscard__]]
251  explicit lock_guard(mutex_type& __m) : _M_device(__m)
252  { _M_device.lock(); }
253 
254  [[__nodiscard__]]
255  lock_guard(mutex_type& __m, adopt_lock_t) noexcept : _M_device(__m)
256  { } // calling thread owns mutex
257 
258  ~lock_guard()
259  { _M_device.unlock(); }
260 
261  lock_guard(const lock_guard&) = delete;
262  lock_guard& operator=(const lock_guard&) = delete;
263 
264  private:
265  mutex_type& _M_device;
266  };
267 
268  /// @} group mutexes
269 _GLIBCXX_END_NAMESPACE_VERSION
270 } // namespace
271 #endif // C++11
272 #endif // _GLIBCXX_MUTEX_H
constexpr try_to_lock_t try_to_lock
Tag used to prevent a scoped lock from blocking if a mutex is locked.
Definition: std_mutex.h:231
constexpr adopt_lock_t adopt_lock
Tag used to make a scoped lock take ownership of a locked mutex.
Definition: std_mutex.h:234
constexpr defer_lock_t defer_lock
Tag used to prevent a scoped lock from acquiring ownership of a mutex.
Definition: std_mutex.h:228
ISO C++ entities toplevel namespace is std.
Do not acquire ownership of the mutex.
Definition: std_mutex.h:218
Try to acquire ownership of the mutex without blocking.
Definition: std_mutex.h:221
Assume the calling thread has already obtained mutex ownership and manage it.
Definition: std_mutex.h:225
A simple scoped lock type.
Definition: std_mutex.h:246