32 Thread support library [thread]

32.5 Mutual exclusion [thread.mutex]

32.5.4 Mutex requirements [thread.mutex.requirements]

32.5.4.5 Shared timed mutex types [thread.sharedtimedmutex.requirements]

32.5.4.5.1 General [thread.sharedtimedmutex.requirements.general]

The standard library type shared_­timed_­mutex is a shared timed mutex type.
Shared timed mutex types meet the requirements of timed mutex types ([thread.timedmutex.requirements]), shared mutex types ([thread.sharedmutex.requirements]), and additionally meet the requirements set out below.
In this description, m denotes an object of a shared timed mutex type, rel_­time denotes an object of an instantiation of duration ([time.duration]), and abs_­time denotes an object of an instantiation of time_­point.
[Note 1:
The shared timed mutex types meet the Cpp17SharedTimedLockable requirements ([thread.req.lockable.shared.timed]).
— end note]
The expression m.try_­lock_­shared_­for(rel_­time) is well-formed and has the following semantics:
Preconditions: The calling thread has no ownership of the mutex.
Effects: Attempts to obtain shared lock ownership for the calling thread within the relative timeout ([thread.req.timing]) specified by rel_­time.
If the time specified by rel_­time is less than or equal to rel_­time.zero(), the function attempts to obtain ownership without blocking (as if by calling try_­lock_­shared()).
The function returns within the timeout specified by rel_­time only if it has obtained shared ownership of the mutex object.
[Note 2:
As with try_­lock(), there is no guarantee that ownership will be obtained if the lock is available, but implementations are expected to make a strong effort to do so.
— end note]
If an exception is thrown then a shared lock has not been acquired for the current thread.
Return type: bool.
Returns: true if the shared lock was acquired, otherwise false.
Synchronization: If try_­lock_­shared_­for() returns true, prior unlock() operations on the same object synchronize with ([intro.multithread]) this operation.
Throws: Timeout-related exceptions ([thread.req.timing]).
The expression m.try_­lock_­shared_­until(abs_­time) is well-formed and has the following semantics:
Preconditions: The calling thread has no ownership of the mutex.
Effects: The function attempts to obtain shared ownership of the mutex.
If abs_­time has already passed, the function attempts to obtain shared ownership without blocking (as if by calling try_­lock_­shared()).
The function returns before the absolute timeout ([thread.req.timing]) specified by abs_­time only if it has obtained shared ownership of the mutex object.
[Note 3:
As with try_­lock(), there is no guarantee that ownership will be obtained if the lock is available, but implementations are expected to make a strong effort to do so.
— end note]
If an exception is thrown then a shared lock has not been acquired for the current thread.
Return type: bool.
Returns: true if the shared lock was acquired, otherwise false.
Synchronization: If try_­lock_­shared_­until() returns true, prior unlock() operations on the same object synchronize with ([intro.multithread]) this operation.
Throws: Timeout-related exceptions ([thread.req.timing]).

32.5.4.5.2 Class shared_­timed_­mutex [thread.sharedtimedmutex.class]

namespace std { class shared_timed_mutex { public: shared_timed_mutex(); ~shared_timed_mutex(); shared_timed_mutex(const shared_timed_mutex&) = delete; shared_timed_mutex& operator=(const shared_timed_mutex&) = delete; // exclusive ownership void lock(); // blocking 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(); // shared ownership void lock_shared(); // blocking 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(); }; }
The class shared_­timed_­mutex provides a non-recursive mutex with shared ownership semantics.
The class shared_­timed_­mutex meets all of the shared timed mutex requirements ([thread.sharedtimedmutex.requirements]).
It is a standard-layout class ([class.prop]).
The behavior of a program is undefined if:
  • it destroys a shared_­timed_­mutex object owned by any thread,
  • a thread attempts to recursively gain any ownership of a shared_­timed_­mutex, or
  • a thread terminates while possessing any ownership of a shared_­timed_­mutex.