33 Thread support library [thread]

33.4 Mutual exclusion [thread.mutex]

33.4.3 Mutex requirements [thread.mutex.requirements]

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

The standard library type shared_­timed_­mutex is a shared timed mutex type. Shared timed mutex types shall meet the requirements of timed mutex types, shared mutex types, and additionally shall meet the requirements set out below. In this description, m denotes an object of a shared timed mutex type, rel_­type denotes an object of an instantiation of duration, and abs_­time denotes an object of an instantiation of time_­point.

The expression m.try_­lock_­shared_­for(rel_­time) shall be well-formed and have the following semantics:

Requires: 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 shall return within the timeout specified by rel_­time only if it has obtained shared ownership of the mutex object. [Note: 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 shall not have been acquired for the current thread.

Return type: bool.

Returns: true if the shared lock was acquired, false otherwise.

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) shall be well-formed and have the following semantics:

Requires: 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 shall return before the absolute timeout ([thread.req.timing]) specified by abs_­time only if it has obtained shared ownership of the mutex object. [Note: 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 shall not have been acquired for the current thread.

Return type: bool.

Returns: true if the shared lock was acquired, false otherwise.

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]).

33.4.3.5.1 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 shall satisfy all of the shared timed mutex requirements. It shall be a standard-layout class (Clause [class]).

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.