Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/named req/Mutex"

From cppreference.com
< cpp‎ | named req
m (missed "Throws: nothing" for m.try_lock 30.4.1.2[thread.mutex.requirements.mutex]/20)
m (.)
 
(11 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
{{cpp/concept/title|Mutex}}
+
{{cpp/named req/title|Mutex|notes={{mark since c++11}}}}
−
{{cpp/concept/navbar}}
+
{{cpp/named req/navbar}}
  
−
The {{tt|Mutex}} concept extends the {{concept|Lockable}} concept to include inter-thread synchronization.
+
The {{named req|Mutex}} requirements extends the {{named req|Lockable}} requirements to include inter-thread synchronization.
  
 
===Requirements===
 
===Requirements===
−
 
+
* {{named req|Lockable}}
−
* {{concept|Lockable}}
+
* {{named req|DefaultConstructible}}
−
* {{concept|DefaultConstructible}}
+
* {{named req|Destructible}}
−
* {{concept|Destructible}}
+
 
* not copyable
 
* not copyable
 
* not movable
 
* not movable
  
−
For object {{ttb|m}} of {{tt|Mutex}} type.
+
For an object {{ttb|m}} of {{named req/core|Mutex}} type:
 
* The expression {{c|m.lock()}} has the following properties
 
* The expression {{c|m.lock()}} has the following properties
 
:* Behaves as an atomic operation.
 
:* Behaves as an atomic operation.
 
:* Blocks the calling thread until exclusive ownership of the mutex can be obtained.
 
:* Blocks the calling thread until exclusive ownership of the mutex can be obtained.
−
:* Prior {{c|m.unlock()}} operations on the same mutex ''synchronize-with'' this lock operation (equivalent to release-acquire {{lc|std::memory_order}})
+
:* Prior {{c|m.unlock()}} operations on the same mutex ''synchronize-with'' this lock operation (equivalent to release-acquire {{lc|std::memory_order}}).
−
:* The behavior is undefined if the calling thread already owns the mutex (except if m is {{lc|std::recursive_mutex}} or {{lc|std::recursive_timed_mutex}})
+
:* The behavior is undefined if the calling thread already owns the mutex (except if m is {{lc|std::recursive_mutex}} or {{lc|std::recursive_timed_mutex}}).
 
:* Exception of type {{lc|std::system_error}} may be thrown on errors, with the following error codes:
 
:* Exception of type {{lc|std::system_error}} may be thrown on errors, with the following error codes:
−
::* {{lc|std::errc::operation_not_permitted}} if the calling thread does not have required privileges
+
::* {{lc|std::errc::operation_not_permitted}} if the calling thread does not have required privileges.
−
::* {{lc|std::errc::resource_deadlock_would_occur}} if the implementation detects that this operation would lead to deadlock
+
::* {{lc|std::errc::resource_deadlock_would_occur}} if the implementation detects that this operation would lead to deadlock.
−
::* {{lc|std::errc::device_or_resource_busy}} if the mutex is already locked
+
 
* The expression {{c|m.try_lock()}} has the following properties
 
* The expression {{c|m.try_lock()}} has the following properties
 
:* Behaves as an atomic operation.
 
:* Behaves as an atomic operation.
 
:* Attempts to obtain exclusive ownership of the mutex for the calling thread without blocking. If ownership is not obtained, returns immediately. The function is allowed to spuriously fail and return even if the mutex is not currently owned by another thread.
 
:* Attempts to obtain exclusive ownership of the mutex for the calling thread without blocking. If ownership is not obtained, returns immediately. The function is allowed to spuriously fail and return even if the mutex is not currently owned by another thread.
−
:* If {{tt|try_lock()}} succeeds, prior {{tt|unlock()}} operations on the same object ''synchronize-with'' this operation (equivalent to release-acquire {{lc|std::memory_order}}). {{tt|lock()}} does not synchronize with a failed {{tt|try_lock()}}
+
:* If {{tt|try_lock()}} succeeds, prior {{tt|unlock()}} operations on the same object ''synchronize-with'' this operation (equivalent to release-acquire {{lc|std::memory_order}}). {{tt|lock()}} does not synchronize with a failed {{tt|try_lock()}}.
 
:* Does not throw exceptions.
 
:* Does not throw exceptions.
 
* The expression {{c|m.unlock()}} has the following properties
 
* The expression {{c|m.unlock()}} has the following properties
Line 32: Line 30:
 
:* The behavior is undefined if the calling thread does not own the mutex.
 
:* The behavior is undefined if the calling thread does not own the mutex.
 
:* Does not throw exceptions.
 
:* Does not throw exceptions.
−
* All lock and unlock operations on a single mutex occur in a single total order
+
* All lock and unlock operations on a single mutex occur in a single total order that can be viewed as [[cpp/atomic/memory_order#Modification_order|modification order]] of an atomic variable: the order is specific to this individual mutex.
  
 
===Library types===
 
===Library types===
−
The following standard library types satisfy {{concept|Mutex}}:
+
The following standard library types satisfy {{named req|Mutex}}:
 
* {{lc|std::mutex}}
 
* {{lc|std::mutex}}
 
* {{lc|std::recursive_mutex}}
 
* {{lc|std::recursive_mutex}}
Line 41: Line 39:
 
* {{lc|std::recursive_timed_mutex}}
 
* {{lc|std::recursive_timed_mutex}}
 
* {{lc|std::shared_mutex}}
 
* {{lc|std::shared_mutex}}
 +
 +
===Defect reports===
 +
{{dr list begin}}
 +
{{dr list item|wg=lwg|dr=2309|std=C++11|before={{tt|lock}} might throw {{lc|std::system_error}}<br>with error code {{lc|std::errc::device_or_resource_busy}}|after=not allowed}}
 +
{{dr list end}}
  
 
===See also===
 
===See also===
 
* [[cpp/thread|Thread support library]]
 
* [[cpp/thread|Thread support library]]
−
* {{concept|Lockable}}
+
* {{named req|Lockable}}
−
* {{concept|TimedMutex}}
+
* {{named req|TimedMutex}}
  
−
[[de:cpp/concept/Mutex]]
+
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
−
[[es:cpp/concept/Mutex]]
+
−
[[fr:cpp/concept/Mutex]]
+
−
[[it:cpp/concept/Mutex]]
+
−
[[ja:cpp/concept/Mutex]]
+
−
[[pt:cpp/concept/Mutex]]
+
−
[[ru:cpp/concept/Mutex]]
+
−
[[zh:cpp/concept/Mutex]]
+

Latest revision as of 07:18, 8 October 2023

 
C++
 
C++ named requirements
 

The Mutex requirements extends the Lockable requirements to include inter-thread synchronization.

Contents

[edit] Requirements

For an object m of Mutex type:

  • The expression m.lock() has the following properties
  • Behaves as an atomic operation.
  • Blocks the calling thread until exclusive ownership of the mutex can be obtained.
  • Prior m.unlock() operations on the same mutex synchronize-with this lock operation (equivalent to release-acquire std::memory_order).
  • The behavior is undefined if the calling thread already owns the mutex (except if m is std::recursive_mutex or std::recursive_timed_mutex).
  • Exception of type std::system_error may be thrown on errors, with the following error codes:
  • The expression m.try_lock() has the following properties
  • Behaves as an atomic operation.
  • Attempts to obtain exclusive ownership of the mutex for the calling thread without blocking. If ownership is not obtained, returns immediately. The function is allowed to spuriously fail and return even if the mutex is not currently owned by another thread.
  • If try_lock() succeeds, prior unlock() operations on the same object synchronize-with this operation (equivalent to release-acquire std::memory_order). lock() does not synchronize with a failed try_lock().
  • Does not throw exceptions.
  • The expression m.unlock() has the following properties
  • Behaves as an atomic operation.
  • Releases the calling thread's ownership of the mutex and synchronizes-with the subsequent successful lock operations on the same object.
  • The behavior is undefined if the calling thread does not own the mutex.
  • Does not throw exceptions.
  • All lock and unlock operations on a single mutex occur in a single total order that can be viewed as modification order of an atomic variable: the order is specific to this individual mutex.

[edit] Library types

The following standard library types satisfy Mutex:

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior
LWG 2309 C++11 lock might throw std::system_error
with error code std::errc::device_or_resource_busy 		not allowed

[edit] See also

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/named_req/Mutex&oldid=160327"