Std::Recursive_Timed_Mutex::Try_Lock_For Member Function
Attempts to acquire a lock on a std::recursive_timed_mutex object for the current thread.
Declaration
template<typename Rep,typename Period>
bool try_lock_for(
std::chrono::duration<Rep,Period> const& relative_time);
Effects
Attempts to acquire a lock on *this for the calling thread within the time specified by relative_time. If relative_time.count() is zero or negative, the call will return immediately, as if it was a call to try_lock(). Otherwise, the call blocks until either the lock has been acquired or the time period specified by relative_time has elapsed.
Returns
true if a lock was obtained for the calling thread, false otherwise.
Postconditions
*this is locked by the calling thread if the function returns
true.
Throws
Nothing.
Note
If the calling thread already holds the lock on *this, the function returns true and the count of locks on *this held by the calling thread is increased by one. If the current thread doesn’t already hold a lock on *this, the function may fail to acquire the lock (and return false) even if no other thread holds a lock on *this. The thread may be blocked for longer than the specified duration. Where possible, the elapsed time is determined by a steady clock.
Std::Recursive_Timed_Mutex::Try_Lock_Until Member Function
Attempts to acquire a lock on a std::recursive_timed_mutex object for the current thread.
Declaration
template<typename Clock,typename Duration>
bool try_lock_until(
std::chrono::time_point<Clock,Duration> const& absolute_time);
Effects
Attempts to acquire a lock on *this for the calling thread before the time specified by absolute_time. If absolute_time<=Clock::now() on entry, the call will return immediately, as if it was a call to try_lock(). Otherwise, the call blocks until either the lock has been acquired or Clock::now() returns a time equal to or later than absolute_time.
Returns
true if a lock was obtained for the calling thread, false otherwise.
Postconditions
*this is locked by the calling thread if the function returns true.
Throws
Nothing.
Note
If the calling thread already holds the lock on *this, the function returns true and the count of locks on *this held by the calling thread is increased by one. If the current thread doesn’t already hold a lock on *this, the function may fail to acquire the lock (and return false) even if no other thread holds a lock on *this. There’s no guarantee as to how long the calling thread will be blocked, only that if the function returns false, then Clock::now() returns a time equal to or later than absolute_time at the point at which the thread became unblocked.
Std::Recursive_Timed_Mutex::Unlock Member Function
Releases a lock on a std::recursive_timed_mutex object held by the current thread.
Declaration
void unlock();
Preconditions
The calling thread must hold a lock on *this.
Effects
Releases a lock on *this held by the current thread. If this is the last lock on *this held by the calling thread, any threads are blocked waiting to acquire a lock on *this. Unblocks one of them.
Postconditions
The number of locks on *this held by the calling thread is reduced by one.
Throws
Nothing.
D.5.5. std::lock_guard class template
The std::lock_guard class template provides a basic lock ownership wrapper. The type of mutex being locked is specified by template parameter Mutex and must meet the Lockable requirements. The specified mutex is locked in the constructor and unlocked in the destructor. This provides a simple means of locking a mutex for a block of code and ensuring that the mutex is unlocked when the block is left, whether that’s by running off the end, by the use of a control flow statement such as break or return, or by throwing an exception.
Instances of std::lock_guard are not MoveConstructible, CopyConstructible, or CopyAssignable.
Class definition
template <class Mutex>
class lock_guard
{
public:
typedef Mutex mutex_type;
explicit lock_guard(mutex_type& m);
lock_guard(mutex_type& m, adopt_lock_t);
~lock_guard();
lock_guard(lock_guard const& ) = delete;
lock_guard& operator=(lock_guard const& ) = delete;
};
Std::Lock_Guard Locking Constructor
Constructs a std::lock_guard instance that locks the supplied mutex.
Declaration
explicit lock_guard(mutex_type& m);
Effects
Constructs a std::lock_guard instance that references the supplied mutex. Calls m.lock().
Throws
Any exceptions thrown by m.lock().
Postconditions
*this owns a lock on m.
Std::Lock_Guard Lock-Adopting Constructor
Constructs a std::lock_guard instance that owns the lock on the supplied mutex.
Declaration
lock_guard(mutex_type& m,std::adopt_lock_t);
Preconditions
The calling thread must own a lock on m.
Effects
Constructs a std::lock_guard instance that references the supplied mutex and takes ownership of the lock on m held by the calling thread.
Nothing.
Postconditions
*this owns the lock on m held by the calling thread.
Std::Lock_Guard Destructor
Destroys a std::lock_guard instance and unlocks the corresponding mutex.
Declaration
~lock_guard();
Effects
Calls m.unlock() for the mutex instance m supplied when *this was constructed.
Throws
Nothing.
D.5.6. std::unique_lock class template
The std::unique_lock class template provides a more general lock ownership wrapper than std::lock_guard. The type of mutex being locked is specified by the template parameter Mutex, which must meet the BasicLockable requirements. In general, the specified mutex is locked in the constructor and unlocked in the destructor, although additional constructors and member functions are provided to allow other possibilities. This provides a means of locking a mutex for a block of code and ensuring that the mutex is unlocked when the block is left, whether that’s by running off the end, by the use of a control flow statement such as break or return, or by throwing an exception. The wait functions of std::condition_variable require an instance of std::unique_lock<std::mutex>, and all instantiations of std::unique_lock are suitable for use with the Lockable parameter for the std::condition_variable_any wait functions.
If the supplied Mutex type meets the Lockable requirements, then std::unique_lock<Mutex> also meets the Lockable requirements. If, in addition, the supplied Mutex type meets the TimedLockable requirements, then std::unique_lock<Mutex> also meets the TimedLockable requirements.
Instances of std::unique_lock are MoveConstructible and MoveAssignable but not CopyConstructible or CopyAssignable.
Class definition
template <class Mutex>
class unique_lock
{
public:
typedef Mutex mutex_type;
unique_lock() noexcept;
explicit unique_lock(mutex_type& m);
unique_lock(mutex_type& m, adopt_lock_t);
unique_lock(mutex_type& m, defer_lock_t) noexcept;
unique_lock(mutex_type& m, try_to_lock_t);
template<typename Clock,typename Duration>
unique_lock(
mutex_type& m,
std::chrono::time_point<Clock,Duration> const& absolute_time);
template<typename Rep,typename Period>
unique_lock(
mutex_type& m,
std::chrono::duration<Rep,Period> const& relative_time);
~unique_lock();
unique_lock(unique_lock const& ) = delete;
unique_lock& operator=(unique_lock const& ) = delete;
unique_lock(unique_lock&& );
unique_lock& operator=(unique_lock&& );
void swap(unique_lock& other) noexcept;
void lock();
bool try_lock();
template<typename Rep, typename Period>
bool try_lock_for(
std::chrono::duration<Rep,Period> const& relative_time);
template<typename Clock, typename Duration>
bool try_lock_until(
std::chrono::time_point<Clock,Duration> const& absolute_time);
void unlock();
explicit operator bool() const noexcept;
bool owns_lock() const noexcept;
Mutex* mutex() const noexcept;
Mutex* release() noexcept;
};
Std::Unique_Lock Default Constructor
Constructs a std::unique_lock instance with no associated mutex.
Declaration
unique_lock() noexcept;
Effects
Constructs a std::unique_lock instance that has no associated mutex.
Postconditions
this->mutex()==NULL, this->owns_lock()==false.
Std::Unique_Lock Locking Constructor
Constructs a std::unique_lock instance that locks the supplied mutex.
Declaration
explicit unique_lock(mutex_type& m);
Effects
Constructs a std::unique_lock instance that references the supplied mutex. Calls m.lock().
Any exceptions thrown by m.lock().
Postconditions
this->owns_lock()==true, this->mutex()==&m.
Std::Unique_Lock Lock-Adopting Constructor
Constructs a std::unique_lock instance that owns the lock on the supplied mutex.
Declaration
unique_lock(mutex_type& m,std::adopt_lock_t);
Preconditions
The calling thread must own a lock on m.
Effects
Constructs a std::unique_lock instance that references the supplied mutex and takes ownership of the lock on m held by the calling thread.
Throws
Nothing.
Postconditions
this->owns_lock()==true, this->mutex()==&m.
Std::Unique_Lock Deferred-Lock Constructor
Constructs a std::unique_lock instance that doesn’t own the lock on the supplied mutex.
Declaration
unique_lock(mutex_type& m,std::defer_lock_t) noexcept;
Effects
Constructs a std::unique_lock instance that references the supplied mutex.
Throws
Nothing.
Postconditions
this->owns_lock()==false, this->mutex()==&m.
Std::Unique_Lock Try-to-Lock Constructor
Constructs a std::unique_lock instance associated with the supplied mutex and tries to acquire a lock on that mutex.
Declaration
unique_lock(mutex_type& m,std::try_to_lock_t);
Preconditions
The Mutex type used to instantiate std::unique_lock must meet the Lockable requirements.
Effects
Constructs a std::unique_lock instance that references the supplied mutex. Calls m.try_lock().
Nothing.
Postconditions
this->owns_lock() returns the result of the m.try_lock() call, this->mutex()==&m.
Std::Unique_Lock Try-to-Lock Constructor With a Duration Timeout
Constructs a std::unique_lock instance associated with the supplied mutex and tries to acquire a lock on that mutex.
Declaration
template<typename Rep,typename Period>
unique_lock(
mutex_type& m,
std::chrono::duration<Rep,Period> const& relative_time);
Preconditions
The Mutex type used to instantiate std::unique_lock must meet the Timed-Lockable requirements.
Effects
Constructs a std::unique_lock instance that references the supplied mutex. Calls m.try_lock_for(relative_time).
Throws
Nothing.
Postconditions
this->owns_lock() returns the result of the m.try_lock_for() call, this->mutex()==&m.
Std::Unique_Lock Try-to-Lock Constructor With a Time_Point Timeout
Constructs a std::unique_lock instance associated with the supplied mutex and tries to acquire a lock on that mutex.
Declaration
template<typename Clock,typename Duration>
unique_lock(
mutex_type& m,
std::chrono::time_point<Clock,Duration> const& absolute_time);
Preconditions
The Mutex type used to instantiate std::unique_lock must meet the Timed-Lockable requirements.
Effects
Constructs a std::unique_lock instance that references the supplied mutex. Calls m.try_lock_until(absolute_time).
Throws
Nothing.
this->owns_lock() returns the result of the m.try_lock_until() call, this->mutex()==&m.
Std::Unique_Lock Move-Constructor
Transfers ownership of a lock from one std::unique_lock object to a newly created std::unique_lock object.
Declaration
unique_lock(unique_lock&& other) noexcept;
Effects
Constructs a std::unique_lock instance. If other owned a lock on a mutex prior to the constructor invocation, that lock is now owned by the newly created std::unique_lock object.
Postconditions
For a newly constructed std::unique_lock object x, x.mutex() is equal to the value of other.mutex() prior to the constructor invocation, and x.owns_lock() is equal to the value of other.owns_lock() prior to the constructor invocation. other.mutex()==NULL, other.owns_lock()==false.
Throws
Nothing.
Note
std::unique_lock objects are not CopyConstructible, so there’s no copy constructor, only this move constructor.
Std::Unique_Lock Move-Assignment Operator
Transfers ownership of a lock from one std::unique_lock object to another std::unique_lock object.
Declaration
unique_lock& operator=(unique_lock&& other) noexcept;
Effects
If this->owns_lock() returns true prior to the call, calls this->unlock(). If other owned a lock on a mutex prior to the assignment, that lock is now owned by *this.
Postconditions
this->mutex() is equal to the value of other.mutex() prior to the assignment, and this->owns_lock() is equal to the value of other.owns_lock() prior to the assignment. other.mutex()==NULL, other.owns_lock()==false.
Throws
Nothing.
Note
std::unique_lock objects are not CopyAssignable, so there’s no copy-assignment operator, only this move-assignment operator.
Std::Unique_Lock Destructor
Destroys a std::unique_lock instance and unlocks the corresponding mutex if it’s owned by the destroyed instance.
Declaration
~unique_lock();
Effects
If this->owns_lock() returns true, calls this->mutex()->unlock().
Throws
Nothing.
Std::Unique_Lock::Swap Member Function
Exchanges ownership of their associated unique_locks of execution between two std::unique_lock objects.
Declaration
void swap(unique_lock& other) noexcept;
Effects
If other owns a lock on a mutex prior to the call, that lock is now owned by *this. If *this owns a lock on a mutex prior to the call, that lock is now owned by other.
Postconditions
this->mutex() is equal to the value of other.mutex() prior to the call. other.mutex() is equal to the value of this->mutex() prior to the call. this->owns_lock() is equal to the value of other.owns_lock() prior to the call. other.owns_lock() is equal to the value of this->owns_lock() prior to the call.
Throws
Nothing.
Swap Nonmember Function for Std::Unique_Lock
Exchanges ownership of their associated mutex locks between two std::unique_lock objects.
Declaration
void swap(unique_lock& lhs,unique_lock& rhs) noexcept;
Effects
lhs.swap(rhs)
Throws
Nothing.
Std::Unique_Lock::Lock Member Function
Acquires a lock on the mutex associated with *this.
Declaration
void lock();
Preconditions
this->mutex()!=NULL, this->owns_lock()==false.
Calls this->mutex()->lock().
Throws
Any exceptions thrown by this->mutex()->lock(). std::system_error with an error code of std::errc::operation_not_permitted if this->mutex()==NULL. std::system_error with an error code of std::errc::resource_deadlock_would_occur if this->owns_lock()==true on entry.
Postconditions
this->owns_lock()==true.
Std::Unique_Lock::Try_Lock Member Function
Attempts to acquire a lock on the mutex associated with *this.
Declaration
bool try_lock();
Preconditions
The Mutex type used to instantiate std::unique_lock must meet the Lockable requirements. this->mutex()!=NULL, this->owns_lock()==false.
Effects
Calls this->mutex()->try_lock().
Returns
true if the call to this->mutex()->try_lock() returned true, false otherwise.
Throws
Any exceptions thrown by this->mutex()->try_lock(). std::system_error with an error code of std::errc::operation_not_permitted if this->mutex()==NULL. std::system_error with an error code of std::errc::resource_deadlock_would_occur if this->owns_lock()==true on entry.
Postconditions
If the function returns true, this->owns_lock()==true, otherwise this->owns_lock()==false.
Std::Unique_Lock::Unlock Member Function
Releases a lock on the mutex associated with *this.
Declaration
void unlock();
Preconditions
this->mutex()!=NULL, this->owns_lock()==true.
Effects
Calls this->mutex()->unlock().
Throws
Any exceptions thrown by this->mutex()->unlock(). std::system_error with an error code of std::errc::operation_not_permitted if this->owns_lock()==false on entry.
this->owns_lock()==false.
Std::Unique_Lock::Try_Lock_for Member Function
Attempts to acquire a lock on the mutex associated with *this within the time specified.
Declaration
template<typename Rep, typename Period>
bool try_lock_for(
std::chrono::duration<Rep,Period> const& relative_time);
Preconditions
The Mutex type used to instantiate std::unique_lock must meet the TimedLockable requirements. this->mutex()!=NULL, this->owns_lock()==false.
Effects
Calls this->mutex()->try_lock_for(relative_time).
Returns
true if the call to this->mutex()->try_lock_for() returned true, false otherwise.
Throws
Any exceptions thrown by this->mutex()->try_lock_for(). std::system_error with an error code of std::errc::operation_not_permitted if this->mutex()==NULL. std::system_error with an error code of std::errc::resource_deadlock_would_occur if this->owns_lock()==true on entry.
Postconditions
If the function returns true, this->owns_lock()==true, otherwise this->owns_lock()==false.
Std::Unique_Lock::Try_Lock_Until Member Function
Attempts to acquire a lock on the mutex associated with *this within the time specified.
Declaration
template<typename Clock, typename Duration>
bool try_lock_until(
std::chrono::time_point<Clock,Duration> const& absolute_time);
Preconditions
The Mutex type used to instantiate std::unique_lock must meet the Timed-Lockable requirements. this->mutex()!=NULL, this->owns_lock()==false.
Effects
Calls this->mutex()->try_lock_until(absolute_time).
Returns
true if the call to this->mutex()->try_lock_until() returned true, false otherwise.
Any exceptions thrown by this->mutex()->try_lock_until(). std::system_error with an error code of std::errc::operation_not_permitted if this->mutex()==NULL. std::system_error with an error code of std::errc::resource_deadlock_would_occur if this->owns_lock()==true on entry.
Postcondition
If the function returns true, this->owns_lock()==true, otherwise this->owns_lock()==false.
Std::Unique_Lock::Operator Bool Member Function
Checks whether or not *this owns a lock on a mutex.
Declaration
explicit operator bool() const noexcept;
Returns
this->owns_lock().
Throws
Nothing.
Note
This is an explicit conversion operator, so it’s only implicitly called in contexts where the result is used as a Boolean and not where the result would be treated as an integer value 0 or 1.
Std::Unique_Lock::Owns_Lock Member Function
Checks whether or not *this owns a lock on a mutex.
Declaration
bool owns_lock() const noexcept;
Returns
true if *this owns a lock on a mutex, false otherwise.
Throws
Nothing.
Std::Unique_Lock::Mutex Member Function
Returns the mutex associated with *this if any.
Declaration
mutex_type* mutex() const noexcept;
Returns
A pointer to the mutex associated with *this if any, NULL otherwise.
Throws
Nothing.
Std::Unique_Lock::Release Member Function
Returns the mutex associated with *this if any, and releases that association.
Declaration
mutex_type* release() noexcept;
Breaks the association of the mutex with *this without unlocking any locks held.
Returns
A pointer to the mutex associated with *this prior to the call if any, NULL otherwise.
Postconditions
this->mutex()==NULL, this->owns_lock()==false.
Throws
Nothing.
Note
If this->owns_lock() would have returned true prior to the call, the caller would now be responsible for unlocking the mutex.
D.5.7. std::lock function template
The std::lock function template provides a means of locking more than one mutex at the same time, without risk of deadlock resulting from inconsistent lock orders.
Declaration
template<typename LockableType1,typename... LockableType2> void lock(LockableType1& m1,LockableType2& m2...);
Preconditions
The types of the supplied lockable objects LockableType1, LockableType2,... shall conform to the Lockable requirements.
Effects
Acquires a lock on each of the supplied lockable objects m1, m2,... by an unspecified sequence of calls to the lock(), try_lock(), and unlock() members of those types that avoid deadlock.
Postconditions
The current thread owns a lock on each of the supplied lockable objects.
Throws
Any exceptions thrown by the calls to lock(), try_lock(), and unlock().
Note
If an exception propagates out of the call to std::lock, then unlock() shall have been called for any of the objects m1, m2,... for which a lock has been acquired in the function by a call to lock() or try_lock().
D.5.8. std::try_lock function template
The std::try_lock function template allows you to try to lock a set of lockable objects in one go, so either they are all locked or none are locked.
Declaration
template<typename LockableType1,typename... LockableType2> int try_lock(LockableType1& m1,LockableType2& m2...);
The types of the supplied lockable objects LockableType1, LockableType2,... shall conform to the Lockable requirements.
Effects
Tries to acquires a lock on each of the supplied lockable objects m1, m2,... by calling try_lock() on each in turn. If a call to try_lock() returns false or throws an exception, locks already acquired are released by calling unlock() on the corresponding lockable object.
Returns
-1 if all locks were acquired (each call to try_lock() returned true), otherwise the zero-based index of the object for which the call to try_lock() returned false.
Postconditions
If the function returns -1, the current thread owns a lock on each of the supplied lockable objects. Otherwise, any locks acquired by this call have been released.
Throws
Any exceptions thrown by the calls to try_lock().
Note
If an exception propagates out of the call to std::try_lock, then unlock() shall have been called for any of the objects m1, m2,... for which a lock has been acquired in the function by a call to try_lock().
D.5.9. std::once_flag class
Instances of std::once_flag are used with std::call_once to ensure that a particular function is called exactly once, even if multiple threads invoke the call concurrently.
Instances of std::once_flag are not CopyConstructible, CopyAssignable, Move-Constructible, or MoveAssignable.
Class definition
struct once_flag
{
constexpr once_flag() noexcept;
once_flag(once_flag const& ) = delete;
once_flag& operator=(once_flag const& ) = delete;
};
Std::Once_Flag Default Constructor
The std::once_flag default constructor creates a new std::once_flag instance in a state, which indicates that the associated function hasn’t been called.
Declaration
constexpr once_flag() noexcept;
Effects
Constructs a new std::once_flag instance in a state, which indicates that the associated function hasn’t been called. Because this is a constexpr constructor, an instance with static storage duration is constructed as part of the static initialization phase, which avoids race conditions and order-of-initialization problems.
D.5.10. std::call_once function template
std::call_once is used with an instance of std::once_flag to ensure that a particular function is called exactly once, even if multiple threads invoke the call concurrently.
Declaration
template<typename Callable,typename... Args> void call_once(std::once_flag& flag,Callable func,Args args...);
Preconditions
The expression INVOKE(func,args) is valid for the supplied values of func and args. Callable and every member of Args are MoveConstructible.
Effects
Invocations of std::call_once on the same std::once_flag object are serialized. If there has been no prior effective std::call_once invocation on the same std::once_flag object, the argument func (or a copy thereof) is called as-if by INVOKE(func,args), and the invocation of std::call_once is effective if and only if the invocation of func returns without throwing an exception. If an exception is thrown, the exception is propagated to the caller. If there has been a prior effective std::call_once on the same std::once_flag object, the invocation of std::call_once returns without invoking func.
Synchronization
The completion of an effective std::call_once invocation on a std::once_flag object happens-before all subsequent std::call_once invocations on the same std::once_flag object.
Throws
std::system_error when the effects can’t be achieved or for any exception propagated from the invocation of func.
D.6. <ratio> header
The <ratio> header provides support for compile-time rational arithmetic.
Header contents
namespace std
{
template<intmax_t N,intmax_t D=1>
class ratio;
// ratio arithmetic
template <class R1, class R2>
using ratio_add = see description;
template <class R1, class R2>
using ratio_subtract = see description ;
template <class R1, class R2>
using ratio_multiply = see description ;
template <class R1, class R2>
using ratio_divide = see description;
// ratio comparison
template <class R1, class R2>
struct ratio_equal;
template <class R1, class R2>
struct ratio_not_equal;
template <class R1, class R2>
struct ratio_less;
template <class R1, class R2>
struct ratio_less_equal;
template <class R1, class R2>
struct ratio_greater;
template <class R1, class R2>
struct ratio_greater_equal;
typedef ratio<1, 1000000000000000000> atto;
typedef ratio<1, 1000000000000000> femto;
typedef ratio<1, 1000000000000> pico;
typedef ratio<1, 1000000000> nano;
typedef ratio<1, 1000000> micro;
typedef ratio<1, 1000> milli;
typedef ratio<1, 100> centi;
typedef ratio<1, 10> deci;
typedef ratio<10, 1> deca;
typedef ratio<100, 1> hecto;
typedef ratio<1000, 1> kilo;
typedef ratio<1000000, 1> mega;
typedef ratio<1000000000, 1> giga;
typedef ratio<1000000000000, 1> tera;
typedef ratio<1000000000000000, 1> peta;
typedef ratio<1000000000000000000, 1> exa;
}
D.6.1. std::ratio class template
The std::ratio class template provides a mechanism for compile-time arithmetic involving rational values such as one half (std::ratio<1,2>), two thirds (std::ratio<2,3>) or fifteen forty-thirds (std::ratio<15,43>). It’s used within the C++ Standard Library for specifying the period for instantiating the std::chrono::duration class template.
Class definition
template <intmax_t N, intmax_t D = 1>
class ratio
{
public:
typedef ratio<num, den> type;
static constexpr intmax_t num= see below;
static constexpr intmax_t den= see below;
};
Requirements
D may not be zero.
num and den are the numerator and denominator of the fraction N/D reduced to lowest terms. den is always positive. If N and D are the same sign, num is positive; otherwise num is negative.
Examples
ratio<4,6>::num == 2 ratio<4,6>::den == 3 ratio<4,-6>::num == -2 ratio<4,-6>::den == 3
D.6.2. std::ratio_add template alias
The std::ratio_add template alias provides a mechanism for adding two std::ratio values at compile time, using rational arithmetic.
Definition
template <class R1, class R2> using ratio_add = std::ratio<see below>;
Preconditions
R1 and R2 must be instantiations of the std::ratio class template.
Effects
ratio_add<R1,R2> is defined as an alias for an instantiation of std::ratio that represents the sum of the fractions represented by R1 and R2 if that sum can be calculated without overflow. If the calculation of the result overflows, the program is ill formed. In the absence of arithmetic overflow, std::ratio_add<R1,R2> shall have the same num and den values as std::ratio<R1::num * R2::den + R2::num * R1::den, R1::den * R2::den>.
Examples
std::ratio_add<std::ratio<1,3>, std::ratio<2,5> >::num == 11 std::ratio_add<std::ratio<1,3>, std::ratio<2,5> >::den == 15 std::ratio_add<std::ratio<1,3>, std::ratio<7,6> >::num == 3 std::ratio_add<std::ratio<1,3>, std::ratio<7,6> >::den == 2
D.6.3. std::ratio_subtract template alias
The std::ratio_subtract template alias provides a mechanism for subtracting two std::ratio values at compile time, using rational arithmetic.
Definition
template <class R1, class R2> using ratio_subtract = std::ratio<see below>;
Preconditions
R1 and R2 must be instantiations of the std::ratio class template.
Effects
ratio_subtract<R1,R2> is defined as an alias for an instantiation of std::ratio that represents the difference of the fractions represented by R1 and R2 if that difference can be calculated without overflow. If the calculation of the result overflows, the program is ill formed. In the absence of arithmetic overflow, std::ratio_subtract<R1,R2> shall have the same num and den values as std::ratio<R1::num * R2::den - R2::num * R1::den, R1::den * R2::den>.
Examples
std::ratio_subtract<std::ratio<1,3>, std::ratio<1,5> >::num == 2 std::ratio_subtract<std::ratio<1,3>, std::ratio<1,5> >::den == 15 std::ratio_subtract<std::ratio<1,3>, std::ratio<7,6> >::num == -5 std::ratio_subtract<std::ratio<1,3>, std::ratio<7,6> >::den == 6
D.6.4. std::ratio_multiply template alias
The std::ratio_multiply template alias provides a mechanism for multiplying two std::ratio values at compile time, using rational arithmetic.
Definition
template <class R1, class R2> using ratio_multiply = std::ratio<see below>;
Preconditions
R1 and R2 must be instantiations of the std::ratio class template.
Effects
ratio_multiply<R1,R2> is defined as an alias for an instantiation of std::ratio that represents the product of the fractions represented by R1 and R2 if that product can be calculated without overflow. If the calculation of the result overflows, the program is ill formed. In the absence of arithmetic overflow, std::ratio_multiply<R1,R2> shall have the same num and den values as std::ratio<R1::num * R2::num, R1::den * R2::den>.
Examples
std::ratio_multiply<std::ratio<1,3>, std::ratio<2,5> >::num == 2 std::ratio_multiply<std::ratio<1,3>, std::ratio<2,5> >::den == 15 std::ratio_multiply<std::ratio<1,3>, std::ratio<15,7> >::num == 5 std::ratio_multiply<std::ratio<1,3>, std::ratio<15,7> >::den == 7
D.6.5. std::ratio_divide template alias
The std::ratio_divide template alias provides a mechanism for dividing two std::ratio values at compile time, using rational arithmetic.
Definition
template <class R1, class R2> using ratio_divide = std::ratio<see below>;
Preconditions
R1 and R2 must be instantiations of the std::ratio class template.
Effects
ratio_divide<R1,R2> is defined as an alias for an instantiation of std::ratio that represents the result of dividing the fractions represented by R1 and R2 if that result can be calculated without overflow. If the calculation overflows, the program is ill formed. In the absence of arithmetic overflow, std::ratio_divide<R1,R2> shall have the same num and den values as std::ratio<R1::num * R2::den, R1::den *R2::num>.
Examples
std::ratio_divide<std::ratio<1,3>, std::ratio<2,5> >::num == 5 std::ratio_divide<std::ratio<1,3>, std::ratio<2,5> >::den == 6 std::ratio_divide<std::ratio<1,3>, std::ratio<15,7> >::num == 7 std::ratio_divide<std::ratio<1,3>, std::ratio<15,7> >::den == 45
D.6.6. std::ratio_equal class template
The std::ratio_equal class template provides a mechanism for comparing two std::ratio values for equality at compile time, using rational arithmetic.
Class definition
template <class R1, class R2>
class ratio_equal:
public std::integral_constant<
bool,(R1::num == R2::num) && (R1::den == R2::den)>
{};
Preconditions
R1 and R2 must be instantiations of the std::ratio class template.
Examples
std::ratio_equal<std::ratio<1,3>, std::ratio<2,6> >::value == true std::ratio_equal<std::ratio<1,3>, std::ratio<1,6> >::value == false std::ratio_equal<std::ratio<1,3>, std::ratio<2,3> >::value == false std::ratio_equal<std::ratio<1,3>, std::ratio<1,3> >::value == true
D.6.7. std::ratio_not_equal class template
The std::ratio_not_equal class template provides a mechanism for comparing two std::ratio values for inequality at compile time, using rational arithmetic.
Class definition
template <class R1, class R2>
class ratio_not_equal:
public std::integral_constant<bool, !ratio_equal<R1,R2>::value>
{};
Preconditions
R1 and R2 must be instantiations of the std::ratio class template.
Examples
std::ratio_not_equal<std::ratio<1,3>, std::ratio<2,6> >::value == false std::ratio_not_equal<std::ratio<1,3>, std::ratio<1,6> >::value == true std::ratio_not_equal<std::ratio<1,3>, std::ratio<2,3> >::value == true std::ratio_not_equal<std::ratio<1,3>, std::ratio<1,3> >::value == false
D.6.8. Std::Ratio_Less Class Template
The std::ratio_less class template provides a mechanism for comparing two std::ratio values at compile time, using rational arithmetic.
template <class R1, class R2>
class ratio_less:
public std::integral_constant<bool,see below>
{};
Preconditions
R1 and R2 must be instantiations of the std::ratio class template.
Effects
std::ratio_less<R1,R2> derives from std::integral_constant<bool, value >, where value is (R1::num*R2::den) < (R2::num*R1::den). Where possible, implementations shall use a method of calculating the result that avoids overflow. If overflow occurs, the program is ill formed.
Examples
std::ratio_less<std::ratio<1,3>, std::ratio<2,6> >::value == false
std::ratio_less<std::ratio<1,6>, std::ratio<1,3> >::value == true
std::ratio_less<
std::ratio<999999999,1000000000>,
std::ratio<1000000001,1000000000> >::value == true
std::ratio_less<
std::ratio<1000000001,1000000000>,
std::ratio<999999999,1000000000> >::value == false
D.6.9. std::ratio_greater class template
The std::ratio_greater class template provides a mechanism for comparing two std::ratio values at compile time, using rational arithmetic.
Class definition
template <class R1, class R2>
class ratio_greater:
public std::integral_constant<bool,ratio_less<R2,R1>::value>
{};
Preconditions
R1 and R2 must be instantiations of the std::ratio class template.
D.6.10. std::ratio_less_equal class template
The std::ratio_less_equal class template provides a mechanism for comparing two std::ratio values at compile time, using rational arithmetic.
Class definition
template <class R1, class R2>
class ratio_less_equal:
public std::integral_constant<bool,!ratio_less<R2,R1>::value>
{};
Preconditions
R1 and R2 must be instantiations of the std::ratio class template.
D.6.11. std::ratio_greater_equal class template
The std::ratio_greater_equal class template provides a mechanism for comparing two std::ratio values at compile time, using rational arithmetic.
Class definition
template <class R1, class R2>
class ratio_greater_equal:
public std::integral_constant<bool,!ratio_less<R1,R2>::value>
{};
Preconditions
R1 and R2 must be instantiations of the std::ratio class template.
D.7. <thread> header
The <thread> header provides facilities for managing and identifying threads and provides functions for making the current thread sleep.
Header contents
namespace std
{
class thread;
namespace this_thread
{
thread::id get_id() noexcept;
void yield() noexcept;
template<typename Rep,typename Period>
void sleep_for(
std::chrono::duration<Rep,Period> sleep_duration);
template<typename Clock,typename Duration>
void sleep_until(
std::chrono::time_point<Clock,Duration> wake_time);
}
}
D.7.1. std::thread class
The std::thread class is used to manage a thread of execution. It provides a means of starting a new thread of execution and waiting for the completion of a thread of execution. It also provides a means for identifying and provides other functions for managing threads of execution.
Class definition
class thread
{
public:
// Types
class id;
typedef implementation-defined native_handle_type; // optional
// Construction and Destruction
thread() noexcept;
~thread();
template<typename Callable,typename Args...>
explicit thread(Callable&& func,Args&&... args);
// Copying and Moving
thread(thread const& other) = delete;
thread(thread&& other) noexcept;
thread& operator=(thread const& other) = delete;
thread& operator=(thread&& other) noexcept;
void swap(thread& other) noexcept;
void join();
void detach();
bool joinable() const noexcept;
id get_id() const noexcept;
native_handle_type native_handle();
static unsigned hardware_concurrency() noexcept;
};
void swap(thread& lhs,thread& rhs);
Std::Thread::Id Class
An instance of std::thread::id identifies a particular thread of execution.
Class definition
class thread::id
{
public:
id() noexcept;
};
bool operator==(thread::id x, thread::id y) noexcept;
bool operator!=(thread::id x, thread::id y) noexcept;
bool operator<(thread::id x, thread::id y) noexcept;
bool operator<=(thread::id x, thread::id y) noexcept;
bool operator>(thread::id x, thread::id y) noexcept;
bool operator>=(thread::id x, thread::id y) noexcept;
template<typename charT, typename traits>
basic_ostream<charT, traits>&
operator<< (basic_ostream<charT, traits>&& out, thread::id id);
Notes
The std::thread::id value that identifies a particular thread of execution shall be distinct from the value of a default-constructed std::thread::id instance and from any value that represents another thread of execution.
The std::thread::id values for particular threads aren’t predictable and may vary between executions of the same program.
std::thread::id is CopyConstructible and CopyAssignable, so instances of std::thread::id may be freely copied and assigned.
Std::Thread::Id Default Constructor
Constructs a std::thread::id object that doesn’t represent any thread of execution.
Declaration
id() noexcept;
Effects
Constructs a std::thread::id instance that has the singular not any thread value.
Throws
Nothing.
Note
All default-constructed std::thread::id instances store the same value.
Std::Thread::Id Equality Comparison Operator
Compares two instances of std::thread::id to see if they represent the same thread of execution.
Declaration
bool operator==(std::thread::id lhs,std::thread::id rhs) noexcept;
Returns
true if both lhs and rhs represent the same thread of execution or both have the singular not any thread value. false if lhs and rhs represent different threads of execution or one represents a thread of execution and the other has the singular not any thread value.
Throws
Nothing.
Std::Thread::Id Inequality Comparison Operator
Compares two instances of std::thread::id to see if they represent different threads of execution.
Declaration
bool operator!=(std::thread::id lhs,std::thread::id rhs) noexcept;
Returns
!(lhs==rhs)
Throws
Nothing.
Std::Thread::Id Less-Than Comparison Operator
Compares two instances of std::thread::id to see if one lies before the other in the total ordering of thread ID values.
Declaration
bool operator<(std::thread::id lhs,std::thread::id rhs) noexcept;
true if the value of lhs occurs before the value of rhs in the total ordering of thread ID values. If lhs!=rhs, exactly one of lhs<rhs or rhs<lhs returns true and the other returns false. If lhs==rhs, lhs<rhs and rhs<lhs both return false.
Throws
Nothing.
Note
The singular not any thread value held by a default-constructed std::thread::id instance compares less than any std::thread::id instance that represents a thread of execution. If two instances of std::thread::id are equal, neither is less than the other. Any set of distinct std::thread::id values forms a total order, which is consistent throughout an execution of a program. This order may vary between executions of the same program.
Std::Thread::Id Less-Than or Equal Comparison Operator
Compares two instances of std::thread::id to see if one lies before the other in the total ordering of thread ID values or is equal to it.
Declaration
bool operator<=(std::thread::id lhs,std::thread::id rhs) noexcept;
Returns
!(rhs<lhs)
Throws
Nothing.
Std::Thread::Id Greater-Than Comparison Operator
Compares two instances of std::thread::id to see if one lies after the other in the total ordering of thread ID values.
Declaration
bool operator>(std::thread::id lhs,std::thread::id rhs) noexcept;
Returns
rhs<lhs
Throws
Nothing.
Std::Thread::Id Greater-Than Or Equal Comparison Operator
Compares two instances of std::thread::id to see if one lies after the other in the total ordering of thread ID values or is equal to it.
Declaration
bool operator>=(std::thread::id lhs,std::thread::id rhs) noexcept;
Returns
!(lhs<rhs)
Throws
Nothing.
Std::Thread::Id Stream Insertion Operator
Writes a string representation of the std::thread::id value into the specified stream.
Declaration
template<typename charT, typename traits> basic_ostream<charT, traits>& operator<< (basic_ostream<charT, traits>&& out, thread::id id);
Effects
Inserts a string representation of the std::thread::id value into the specified stream.
Returns
out
Throws
Nothing.
Note
The format of the string representation isn’t specified. Instances of std::thread::id that compare equal have the same representation, and instances that aren’t equal have distinct representations.
Std::Thread::Native_Handle_Type Typedef
native_handle_type is a typedef to a type that can be used with platform-specific APIs.
Declaration
typedef implementation-defined native_handle_type;
Note
This typedef is optional. If present, the implementation should provide a type that’s suitable for use with native platform-specific APIs.
Std::Thread::Native_Handle Member Function
Returns a value of type native_handle_type that represents the thread of execution associated with *this.
Declaration
native_handle_type native_handle();
Note
This function is optional. If present, the value returned should be suitable for use with the native platform-specific APIs.
Std::Thread Default Constructor
Constructs a std::thread object without an associated thread of execution.
Declaration
thread() noexcept;
Effects
Constructs a std::thread instance that has no associated thread of execution.
Postconditions
For a newly constructed std::thread object x, x.get_id()==id().
Throws
Nothing.
Std::Thread Constructor
Constructs a std::thread object associated with a new thread of execution.
Declaration
template<typename Callable,typename Args...> explicit thread(Callable&& func,Args&&... args);
Preconditions
func and each element of args must be MoveConstructible.
Effects
Constructs a std::thread instance and associates it with a newly created thread of execution. Copies or moves func and each element of args into internal storage that persists for the lifetime of the new thread of execution. Performs INVOKE (copy-of-func,copy-of-args) on the new thread of execution.
Postconditions
For a newly constructed std::thread object x, x.get_id()!=id().
Throws
An exception of type std::system_error if unable to start the new thread. Any exception thrown by copying func or args into internal storage.
Synchronization
The invocation of the constructor happens-before the execution of the supplied function on the newly created thread of execution.
Std::Thread Move-Constructor
Transfers ownership of a thread of execution from one std::thread object to a newly created std::thread object.
Declaration
thread(thread&& other) noexcept;
Effects
Constructs a std::thread instance. If other has an associated thread of execution prior to the constructor invocation, that thread of execution is now associated with the newly created std::thread object. Otherwise, the newly created std::thread object has no associated thread of execution.
Postconditions
For a newly constructed std::thread object x, x.get_id() is equal to the value of other.get_id() prior to the constructor invocation. other.get_id()==id().
Throws
Nothing.
Note
std::thread objects are not CopyConstructible, so there’s no copy constructor, only this move constructor.
Std::Thread Destructor
Destroys a std::thread object.
Declaration
~thread();
Destroys *this. If *this has an associated thread of execution (this->joinable() would return true), calls std::terminate() to abort the program.
Throws
Nothing.
Std::Thread Move-Assignment Operator
Transfers ownership of a thread of execution from one std::thread object to another std::thread object.
Declaration
thread& operator=(thread&& other) noexcept;
Effects
If this->joinable() returns true prior to the call, calls std::terminate() to abort the program. If other has an associated thread of execution prior to the assignment, that thread of execution is now associated with *this. Otherwise *this has no associated thread of execution.
Postconditions
this->get_id() is equal to the value of other.get_id() prior to the call. other.get_id()==id().
Throws
Nothing.
Note
std::thread objects are not CopyAssignable, so there’s no copy-assignment operator, only this move-assignment operator.
Std::Thread::Swap Member Function
Exchanges ownership of their associated threads of execution between two std::thread objects.
Declaration
void swap(thread& other) noexcept;
Effects
If other has an associated thread of execution prior to the call, that thread of execution is now associated with *this. Otherwise *this has no associated thread of execution. If *this has an associated thread of execution prior to the call, that thread of execution is now associated with other. Otherwise other has no associated thread of execution.
Postconditions
this->get_id() is equal to the value of other.get_id() prior to the call. other.get_id() is equal to the value of this->get_id() prior to the call.
Throws
Nothing.
Swap Nonmember Function For Std::Threads
Exchanges ownership of their associated threads of execution between two std::thread objects.
Declaration
void swap(thread& lhs,thread& rhs) noexcept;
Effects
lhs.swap(rhs)
Throws
Nothing.
Std::Thread::Joinable Member Function
Queries whether or not *this has an associated thread of execution.
Declaration
bool joinable() const noexcept;
Returns
true if *this has an associated thread of execution, false otherwise.
Throws
Nothing.
Std::Thread::Join Member Function
Waits for the thread of execution associated with *this to finish.
Declaration
void join();
Preconditions
this->joinable() would return true.
Effects
Blocks the current thread until the thread of execution associated with *this has finished.
Postconditions
this->get_id()==id(). The thread of execution associated with *this prior to the call has finished.
Synchronization
The completion of the thread of execution associated with *this prior to the call happens-before the call to join() returns.
Throws
std::system_error if the effects can’t be achieved or this->joinable() returns false.
Std::Thread::Detach Member Function
Detaches the thread of execution associated with *this to finish.
Declaration
void detach();
this->joinable() returns true.
Effects
Detaches the thread of execution associated with *this.
Postconditions
this->get_id()==id(), this->joinable()==false
The thread of execution associated with *this prior to the call is detached and no longer has an associated std::thread object.
Throws
std::system_error if the effects can’t be achieved or this->joinable() returns false on invocation.
Std::Thread::Get_Id Member Function
Returns a value of type std::thread::id that identifies the thread of execution associated with *this.
Declaration
thread::id get_id() const noexcept;
Returns
If *this has an associated thread of execution, returns an instance of std::thread::id that identifies that thread. Otherwise returns a default-constructed std::thread::id.
Throws
Nothing.
Std::Thread::Hardware_Concurrency Static Member Function
Returns a hint as to the number of threads that can run concurrently on the current hardware.
Declaration
unsigned hardware_concurrency() noexcept;
Returns
The number of threads that can run concurrently on the current hardware. This may be the number of processors in the system, for example. Where this information is not available or well defined, this function returns 0.
Throws
Nothing.
D.7.2. Namespace this_thread
The functions in the std::this_thread namespace operate on the calling thread.
Std::This_Thread::Get_Id Nonmember Function
Returns a value of type std::thread::id that identifies the current thread of execution.
Declaration
thread::id get_id() noexcept;
An instance of std::thread::id that identifies the current thread.
Throws
Nothing.
Std::This_Thread::Yield Nonmember Function
Used to inform the library that the thread that invoked the function doesn’t need to run at the point of the call. Commonly used in tight loops to avoid consuming excessive CPU time.
Declaration
void yield() noexcept;
Effects
Provides the library an opportunity to schedule something else in place of the current thread.
Throws
Nothing.
Std::This_Thread::Sleep_For Nonmember Function
Suspends execution of the current thread for the specified duration.
Declaration
template<typename Rep,typename Period> void sleep_for(std::chrono::duration<Rep,Period> const& relative_time);
Effects
Blocks the current thread until the specified relative_time has elapsed.
Note
The thread may be blocked for longer than the specified duration. Where possible, the elapsed time is determined by a steady clock.
Throws
Nothing.
Std::This_Thread::Sleep_Until Nonmember Function
Suspends execution of the current thread until the specified time point has been reached.
Declaration
template<typename Clock,typename Duration>
void sleep_until(
std::chrono::time_point<Clock,Duration> const& absolute_time);
Effects
Blocks the current thread until the specified absolute_time has been reached for the specified Clock.
Note
There’s no guarantee as to how long the calling thread will be blocked for, only that Clock::now() returned a time equal to or later than absolute_time at the point at which the thread became unblocked.
Throws
Nothing.