<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
	<title>time_duration</title>

	<style>
	p {text-align:justify}
	li {text-align:justify}
	blockquote.note
	{
		background-color:#E0E0E0;
		padding-left: 15px;
		padding-right: 15px;
		padding-top: 1px;
		padding-bottom: 1px;
	}
	ins {color:#00A000}
	del {color:#A00000}
	</style>

</head>

<body>

<address align=right>
Document number: N2661=08-0171<br>
<br>
<a href="mailto:howard.hinnant@gmail.com">Howard E. Hinnant</a><br>
<a href="mailto:wb@fnal.gov">Walter E. Brown</a><br>
<a href="mailto:jeff@crystalclearsoftware.com">Jeff Garland</a><br>
<a href="mailto:paterno@fnal.gov">Marc Paterno</a><br>
2008-06-11
</address>
<hr>

<h1 align=center>A Foundation to Sleep On</h2>
<h2 align=center>Clocks, Points in Time, and Time Durations</h1>

<h2>Contents</h2>

<ul>
<li><a href="#Introduction">Introduction</a></li>
<li><a href="#History">A Brief History of Time</a></li>
<li><a href="#Goals">Goals</a></li>
<li><a href="#Overview">Overview</a></li>

<li>
<a href="#common_type"><code>common_type</code></a>
<ul>
<li><a href="#common_type_wording"><code>common_type</code> Proposed Wording</a></li>
</ul>
</li>

<li>
<a href="#ratio"><code>ratio</code></a>
<ul>
<li><a href="#ratio_wording"><code>ratio</code> Proposed Wording</a></li>
</ul>
</li>

<li>
<a href="#duration"><code>duration</code></a>
</li>

<li>
<a href="#Clocks">Clocks</a>
</li>

<li>
<a href="#time_point"><code>time_point</code></a>
<ul>
<li><a href="#time_wording">Time Proposed Wording</a></li>
</ul>
</li>

<li>
<a href="#Threads">Threads</a>
<ul>
<li><a href="#Threads_wording">Threads Proposed Wording</a></li>
</ul>
</li>

<li><a href="#Acknowledgements">Acknowledgements</a></li>
</ul>

<h2><a name="Introduction"></a>Introduction</h2>

<p>
We all deal with time every day of our lives.  We've intuitively known
it since birth.  Thus we are all very familiar with it and believe it to
be a simple matter.  The modeling of time in computer programs should be
similarly simple.
</p>

<p>
The unfortunate truth is that this perceived simplicity is only skin
deep.  Fortunately however, we do not need a terribly complicated
solution to meet the bulk of our needs.  However, overly simplistic
solutions are fraught with danger, inherent inefficiency, and lack the
ability to adapt as the computer industry evolves over decades.
</p>

<h2><a name="History"></a>A Brief History of Time</h2>
<h3>(With apologies to Stephen Hawking)</h3>

<p>
The C library has had basic time facilities for several decades.  It
contains both the notion of a point in time, and the time duration
between two points in time.  It also has a clock to get the current time
(point).
</p>

<blockquote><pre>
// A type capable of representing a point in time.
time_t

// A function returning a time duration between two points in time.
double difftime(time_t t1, time_t t2);

// A function returning the current point in time.
time_t time(time_t*);
</pre></blockquote>

<p>
The C library also contains functions relating points in time to the
Gregorian calendar, and for performing I/O with points in time.
</p>

<p>
For a time point to have meaning, one must be able relate or compare two
time points.  This generally requires an epoch which is simply a special
point in time against which all other points in time relate themselves
to.  Without an epoch (or common reference) it becomes impossible to
compare two points in time.  However to compare two points in time, all
one needs to know is that they share the same epoch.  Knowledge of when
that epoch is, isn't needed.
</p>

<p>
The C committee decided to not specify the epoch to which
<code>time_t</code> is measured against, nor the precision it is
measured with.  The advantage of this
is that platforms can more easily change the definition of the epoch
since no code can portably depend on exactly when it was.  If a process
needs to import or export a point in time with another process, it must
first relate the point in time to an agreed upon epoch, such as that
used by the Gregorian calendar.
</p>

<p>
POSIX specified <code>time_t</code> to represent seconds, and over the
decades it has become common for <code>time_t</code> to be a signed 32
bit integral type which is simply a count of seconds since New Years
1970. De-facto standardizing on this definition has created some serious
problems:
</p>

<ul>
<li>
Computers often need to traffic in time durations smaller than a second.
 Since the points in time have only the precision of a second,
<code>difftime</code> can not return a time duration with more precision
than a second.
</li>
<li>
The range of of this representation will overflow at 03:14:07 UTC on
Tuesday, January 19, 2038.
</li>
</ul>

<p>
One solution to the <code>time_t</code> problem is to simply extend it to
a signed 64 bit integer.  This would get rid the of the range problem
forever (for all practical purposes).  However, the precision problem remains.
</p>

<p>
POSIX first published a solution to the precision problem with a new clock to get
"now", and a new representation:
</p>

<blockquote><pre>
struct timeb
{
    time_t time;             // seconds
    unsigned short millitm;  // milliseconds
};

int ftime(struct timeb *tp);
</pre></blockquote>

<p>
This function is currently marked LEGACY in the POSIX documentation.
</p>

<p>
Next came a new clock, and a new structure with microsecond precision:
</p>

<blockquote><pre>
struct timeval
{
    time_t tv_sec;             // seconds
    int_least20_t tv_usec;     // microseconds
};

int gettimeofday(struct timeval *restrict tp, void *restrict tzp);
</pre></blockquote>

<p>
This function is still in wide use today on many platforms.  However,
it is not the end of the line.  POSIX later released a new clock, and
a new structure.  This new function actually supports multiple clocks
and has nanosecond precision.
</p>

<blockquote><pre>
struct timespec
{
    time_t tv_sec;    // seconds
    long tv_nsec;     // nanoseconds
};

int clock_gettime(clockid_t, struct timespec *);
</pre></blockquote>

<p>
In summary, there has been a progression of C interfaces (outside of the C standard) with precisions
of second, millisecond, microsecond and nanosecond.  Each requires a new
interface, both for the structural representation, and for its associated
clock to find the current point in time.
</p>

<p>
Is nanosecond precision the end of the line?  Every computer Apple currently
ships, has a monotonic clock which reports the current time point
in units of a single nanosecond.  Most of these machines have a cpu clock speed
at or above 2GHz.  The amount of time between two ticks of a 2GHz clock is
only one half of a nanosecond (500 picoseconds).
</p>

<p>
The future is always hard to predict.  However, over the next 10 to 20 years,
should the need arise to traffic in time durations finer than nanosecond, we
would not be surprised.  We are already bumping up against 1 nanosecond
precision.
</p>

<p>
Should the C++ committee standardize a time point / time duration
representation with nanosecond precision now?  And be prepared to
standardize yet another representation with finer precision 10
(or even 5) years from now?  In the long run, is such a plan really
simple?  Or does it just seem so when we only have to worry about
nanoseconds today?
</p>

<p>
This paper proposes a solution that is <em>precision neutral</em>.
</p>

<h2><a name="Goals"></a>Goals</h2>

<p>
C++ offers unique opportunities in the representation of time.  Other
languages have had to address this problem as well.  But none of them
had the tools which C++ has which can be put to use in the solution of
this problem. The C++0x standard library's multi-threading library
requires the ability to deal with the representation of time in a manner
consistent with modern C++ practices. This paper proposes a solution
to both the standard library need and C++ user needs
with a very simple end user interface which supports multiple clocks,
multiple precisions (both coarser and finer than we will ever need),
separate types for points in time and time durations, efficiency, and
compile time enforced safety.
</p>

<p>
In addition to the clocks provided by the proposal, users can easily
create their own clocks, with both points in time and time durations
which have a representation and precision of their own choosing.  For
example if there is a hardware counter which simply increments a count
with each cycle of the cpu, one can very easily build clocks, time
points and durations on top of that, using only a few tens of lines of
code.  Such systems can be used to call the time-sensitive threading
API's such as sleep, wait on a condition variable, or wait for a mutex
lock.  The API proposed herein is not sensitive as to whether this is a
300MHz clock (with a 3<span style="font-size: 80%"><sup>1</sup>&frasl;<sub>3</sub></span>
nanosecond tick period) or a 3GHz clock (with
a tick period of&nbsp; <span style="font-size: 80%"> <sup>1</sup>&frasl;<sub>3</sub></span> of a nanosecond).
And the resulting code will be
just as efficient as if the user wrote a special purpose clock cycle
counter.
</p>

<h2><a name="Overview"></a>Overview</h2>

<ul>
<li>
This paper proposes <em>one</em> facility for representing time durations: <code>duration</code>.
Examples of time durations include <code>seconds</code>, <code>minutes</code> and
<code>nanoseconds</code>.  All of these units of time duration are united with a generic interface
by the <code>duration</code> facility.
</li>
<li>
This paper proposes <em>one</em> facility for representing points in time: <code>time_point</code>.
A <code>time_point</code> represents an epoch plus or minus a duration.  This paper leaves
epochs unspecified.  A <code>time_point</code> is associated with a clock.
</li>
<li>
This paper proposes several clocks, some of which may not be available on any given
platform: <code>system_clock</code>, <code>monotonic_clock</code> and <code>high_resolution_clock</code>.
A <code>clock</code> is a symbolic bundle of a <i>native</i> <code>time_point</code> and
<code>duration</code>, and a function which returns a <code>time_point</code> representing <em>now</em>.
</li>
<li>
This paper proposes changes to chapter 30 of the current working draft to take advantage of
the <code>clock</code>s, <code>time_point</code>s and <code>duration</code>s proposed herein.
</li>
</ul>

<p>
Additionally, a minimal amount of general purpose infrastructure is proposed which will
support both the interface and implementation of the <code>clock</code>s,
<code>time_point</code>s and <code>duration</code>s proposed herein.  It is expected that
these general purpose facilities will also find utility in far ranging user applications
as well.
</p>

<ul>
<li>
<code>common_type</code> is a facility which is useful in specifying the type of the result of
functions and operators which take a variety of types (e.g. "mixed mode" complex arithmetic).
</li>
<li>
<code>ratio</code> is a facility which is useful in specifying compile time rational
constants.  Compile time rational arithmetic is supported with protection against overflow
and divide by zero.  Such a facility is very handy when needing to <em>efficiently</em> represent
<span style="font-size: 80%"> <sup>1</sup>&frasl;<sub>3</sub></span> of a
nanosecond, or specifying an inch in terms of meters
(for example <span style="font-size: 80%"><sup>254</sup>&frasl;<sub>10000</sub></span> meters
- which <code>ratio</code> will reduce to
<span style="font-size: 80%"><sup>127</sup>&frasl;<sub>5000</sub></span> meters).
</li>
</ul>

<h3>Sold Separately</h3>

<p>
This paper does not offer calendrical services except for a minimal mapping to
and from C's <code>time_t</code>.
</p>

<blockquote>
<p>
As this paper does not propose a date/time library, nor specify epochs, it also does not address
leap seconds.  However, a date/time library will find this to be an excellent foundation on which to
build.
</p>
</blockquote>

<p>
This paper does not propose a general purpose physical quantities library.
</p>

<blockquote>
<p>
This paper proposes a solid foundation that, in the future, could
provide a compatible starting point for a general physical units
library.  While such a future library might take any of several forms,
the present proposal stops well short of actually being a physical units
library.  This proposal is time-specific, and continues to be motivated
by the time-related needs of the threading library.
</p>
</blockquote>

<p>
The major goal of this proposal is to satisfy the needs of the standard library threading API in a manner
which is easy to use, safe to use, efficient, and flexible enough to not be obsolete 10 or even
100 years from now.  Every feature contained in this proposal is here for a specific reason with
practical use cases as motivation.  Things that fell into the category of "cool", or "that sounds
like it might be useful", or "very useful but not needed by this interface" have not been included.
Such items might appear in other proposals, and possibly target a TR.
</p>

<h3>Impact on existing code</h3>

<p>
The proposal is entirely an add-on. It will break no existing C++03 code,
subject to the usual caveat that user code giving a <code>using namespace
std</code> may see name clashes. Even that possibility is mitigated because
the time portion of the proposal is in a std sub-namespace.
</p>

<h2><a name="common_type"></a><code>common_type</code></h2>

<p>
<code>common_type</code> has been a recurring theme in many places for many years.
We've previously known it as <code>promote</code> and examples of it are spread
throughout <a href="www.boost.org">boost</a>.  It has been reinvented independently
several times, because it is so useful.
</p>

<p>
Andrei Alexandrescu recently pointed us at a D library:
<a href="http://www.digitalmars.com/d/2.0/phobos/std_traits.html#CommonType">std.traits - D Programming Language - Digital Mars</a>,
which became the motivation for this particular name, and the variadic nature
of this trait.
</p>

<p>
In a nutshell, <code>common_type</code> is a trait that takes 1 or more types, and
returns a type which all of the types will convert to.  The default definition demands
this conversion be implicit.  However the trait can be specialized for user-defined
types which want to limit their inter-type conversions to explicit, and yet still
want to interoperate with the <code>common_type</code> facility.
</p>

<p>
Example:
</p>

<blockquote><pre>
template &lt;class T, class U&gt;
typename common_type&lt;complex&lt;T&gt;, complex&lt;U&gt;&gt;::type
operator+(complex&lt;T&gt;, complex&lt;U&gt;);
</pre></blockquote>

<p>
In the above example, "mixed-mode" complex arithmetic is allowed.  The return
type is described by <code>common_type</code>.  For example the resulting type
of adding a <code>complex&lt;int&gt;</code> and <code>complex&lt;double&gt;</code> might be a
<code>complex&lt;double&gt;</code>.  Another choice for the author might be:
</p>

<blockquote><pre>
template &lt;class T, class U&gt;
complex&lt;typename common_type&lt;T, U&gt;::type&gt;
operator+(complex&lt;T&gt;, complex&lt;U&gt;);
</pre></blockquote>

<p>
Here is how someone might produce a variadic comparison function:
</p>

<blockquote><pre>
template &lt;class ...T&gt;
typename common_type&lt;T...&gt;::type
min(T... t);
</pre></blockquote>

<p>
This is a very useful and broadly applicable utility.  The <code>duration</code>
and <code>time_point</code> facilities use it to make multi-precision arithmetic
seamless and exact.
</p>

<p>
The cost of not including <code>common_type</code> is that it is very likely that
the implementation would include it anyway, but spell it <code>__common_type</code> instead.  This
would prevent authors of arithmetic emulators from using their classes as representations
with <code>duration</code>s unless the emulator had exactly one implicit conversion to or from an
arithmetic type.  This would be a large loss of functionality from the user's point
of view, possibly mandating a less safe interface for the user's arithmetic emulator.
</p>

<h3><a name="common_type_wording"></a><code>common_type</code> Proposed Wording</h3>

<p>
Insert into 20.4.2 [meta.type.synop]
</p>

<blockquote><pre>
template &lt;class ...T&gt; struct common_type;
</pre></blockquote>

<p>
Modify 20.4.2 [meta.type.synop] paragraph 1:
</p>

<blockquote>
The behavior of a program that adds specializations for any of the class
templates defined in this subclause is undefined <ins>unless otherwise
specified</ins>.
</blockquote>

<p>
Add a row to 20.4.7 [meta.trans.other]:
</p>

<blockquote><pre>
template &lt;class ...T&gt; struct common_type;

template &lt;class T&gt;
struct common_type&lt;T&gt;
{
    typedef T type;
};

template &lt;class T, class U&gt;
struct common_type&lt;T, U&gt;
{
private:
    static T&amp;&amp; t();
    static U&amp;&amp; u();
public:
    typedef decltype(true ? t() : u()) type;
};

template &lt;class T, class U, class ...V&gt;
struct common_type&lt;T, U, V...&gt;
{
    typedef typename common_type&lt;typename common_type&lt;T, U&gt;::type, V...&gt;::type type;
};
</pre>

<p>
All types in the parameter pack <code>T</code> shall be complete.  This
trait is permitted to be specialized by a user if at least one template parameter is a
user-defined type.  [<i>Note:</i> Such specializations are required when only
explicit conversions are desired among the <code>common_type</code>
arguments. -- <i>end note</i>]
</p>

</blockquote>

<h2><a name="ratio"></a><code>ratio</code></h2>

<p>
<code>ratio</code> is a general purpose utility inspired by Walter Brown allowing one to easily and
safely compute rational values at compile time.  The ratio class
catches all errors (such as divide by zero and overflow) at compile
time.  It is used in the <code>duration</code> and
<code>time_point</code> libraries to efficiently create units of time. 
It can also be used in other "quantity" libraries (both std-defined and
user-defined), or anywhere there is a rational constant which is known at
compile time.  The use of this utility can greatly reduce the chances of
run time overflow because the <code>ratio</code> (and any
<code>ratio</code>s resulting from <code>ratio</code> arithmetic) are
always reduced to lowest terms.
</p>

<p>
<code>ratio</code> is a template taking two <code>intmax_t</code>s, with the
second defaulted to 1.  It only has two public members, both of which are
<code>static const intmax_t</code>.  One is the numerator of the ratio and the
other is the denominator.  The <code>ratio</code> is always normalized such that
it is expressed in lowest terms, and the denominator is always positive.  When
the numerator is 0, the denominator is always 1.
</p>

<p>
Example:
</p>

<blockquote><pre>
typedef ratio&lt;5, 3&gt;   five_thirds;       // five_thirds::num == 5, five_thirds::den == 3
typedef ratio&lt;25, 15&gt; also_five_thirds;  // also_five_thirds::num == 5, also_five_thirds::den == 3
typedef ratio_divide&lt;five_thirds, also_five_thirds&gt;::type one;  // one::num == 1, one::den == 1
</pre></blockquote>

<p>
This facility also includes convenience typedefs for the SI prefixes atto through exa corresponding to
their internationally recognized definitions (in terms of <code>ratio</code>).  This is a tremendous
syntactic convenience.  It will prevent errors in specifying constants as one no longer has to
double count the number of zeros when trying to write million or billion.
</p>

<p>
Example:
</p>

<blockquote><pre>
typedef ratio_multiply&lt;ratio<5>, giga&gt;::type _5giga;  // _5giga::num == 5000000000, _5giga::den == 1
typedef ratio_multiply&lt;ratio<5>, nano&gt;::type _5nano;  // _5nano::num == 1, _5nano::den == 200000000
</pre></blockquote>

<p>
The cost of not including <code>ratio</code> would mean that the implementor would likely have this
functionality anyway, but spell it <code>__ratio</code> instead.  This would prevent the user from
using <code>ratio</code> in his own code.  Furthermore <code>duration</code>
would have to be templated on two <code>long long</code>s instead of on <code>ratio</code> like so:
</p>

<blockquote><pre>
template &lt;class Rep, long long N, long long D&gt; duration
</pre></blockquote>

<p>
This would mean that clients wanting to build a custom duration type (say a nanosecond
represented by a <code>double</code>) would have to write:
</p>

<blockquote><pre>
duration&lt;double, 1, 1000000000LL&gt;
</pre></blockquote>

<p>
instead of:
</p>

<blockquote><pre>
duration&lt;double, nano&gt;
</pre></blockquote>

<p>
This lack of syntatic niceness, along with the loss of functionality in
the reuse of <code>ratio</code> in user-written code seems to indicate
that the loss of <code>ratio</code> would be a sizeable loss to user
code.
</p>

<h3><a name="ratio_wording"></a><code>ratio</code> Proposed Wording</h3>

<p>
Insert a new section in 20 [utilities].
</p>

<blockquote>

<h4>Compile time rational arithmetic [ratio]</h4>

<p>
This  subclause describes a class template <code>ratio</code> which exactly represents
any finite rational number with a numerator and denominator representable by <code>intmax_t</code>.
The numerator and denominator shall be compile time integral constants.
</p>

<h4>Header <code>&lt;ratio&gt;</code> synopsis [ratio.synop]</h4>

<blockquote><pre>
namespace std {
  template &lt;intmax_t N, intmax_t D = 1&gt; class ratio;

  // ratio arithmetic
  template &lt;class R1, class R2&gt; struct ratio_add;
  template &lt;class R1, class R2&gt; struct ratio_subtract;
  template &lt;class R1, class R2&gt; struct ratio_multiply;
  template &lt;class R1, class R2&gt; struct ratio_divide;

  // ratio comparison
  template &lt;class R1, class R2&gt; struct ratio_equal;
  template &lt;class R1, class R2&gt; struct ratio_not_equal;
  template &lt;class R1, class R2&gt; struct ratio_less;
  template &lt;class R1, class R2&gt; struct ratio_less_equal;
  template &lt;class R1, class R2&gt; struct ratio_greater;
  template &lt;class R1, class R2&gt; struct ratio_greater_equal;

  // convenience SI typedefs
  typedef ratio&lt;1, 1000000000000000000000000&gt; yocto;  // conditionally supported
  typedef ratio&lt;1,    1000000000000000000000&gt; zepto;  // conditionally supported
  typedef ratio&lt;1,       1000000000000000000&gt; atto;
  typedef ratio&lt;1,          1000000000000000&gt; femto;
  typedef ratio&lt;1,             1000000000000&gt; pico;
  typedef ratio&lt;1,                1000000000&gt; nano;
  typedef ratio&lt;1,                   1000000&gt; micro;
  typedef ratio&lt;1,                      1000&gt; milli;
  typedef ratio&lt;1,                       100&gt; centi;
  typedef ratio&lt;1,                        10&gt; deci;
  typedef ratio&lt;                       10, 1&gt; deca;
  typedef ratio&lt;                      100, 1&gt; hecto;
  typedef ratio&lt;                     1000, 1&gt; kilo;
  typedef ratio&lt;                  1000000, 1&gt; mega;
  typedef ratio&lt;               1000000000, 1&gt; giga;
  typedef ratio&lt;            1000000000000, 1&gt; tera;
  typedef ratio&lt;         1000000000000000, 1&gt; peta;
  typedef ratio&lt;      1000000000000000000, 1&gt; exa;
  typedef ratio&lt;   1000000000000000000000, 1&gt; zetta;  // conditionally supported
  typedef ratio&lt;1000000000000000000000000, 1&gt; yotta;  // conditionally supported
}  // namespace std
</pre></blockquote>

<h4><code>ratio</code> [ratio.ratio]</h4>

<blockquote><pre>
namespace std {
  template &lt;intmax_t N, intmax_t D = 1&gt;
  class ratio
  {
  public:
    static const intmax_t num;
    static const intmax_t den;
  };
}  // namespace std
</pre>

<p>
A diagnostic shall be emitted if <code>ratio</code> is instantiated with
<code>D == 0</code>, or if the absolute value of <code>N</code> or <code>D</code>
can not be represented.
[<i>Note:</i> These rules ensure that infinite ratios are avoided and that
for any negative input, there exists a representable value of its absolute
value which is positive.  In a two's complement representation, this excludes
the most negative value. <i>-- end note</i>]
</p>

<p>
Let <code>gcd</code> denote the greatest common divisor of <code>N</code>'s absolute value
and of <code>D</code>'s absolute value.
</p>

<p>
<code>num</code> shall have the value <code>sign(N)*sign(D)*abs(N)/gcd</code>.
</p>

<p>
<code>den</code> shall have the value <code>abs(D)/gcd</code>.
</p>

</blockquote>

<h4><code>ratio</code> arithmetic [ratio.arithmetic]</h4>

<blockquote>
<p>
For each of the class templates in this clause, each template parameter shall
refer to a <code>ratio</code>. If the implementation is unable to form the
indicated <code>ratio</code> due to overflow, a diagnostic shall be issued.
</p>
<pre>
template &lt;class R1, class R2&gt; struct ratio_add      {typedef <i>see below</i> type;};
</pre>
<blockquote>
<code>type</code> shall alias <code>ratio&lt;R1::num * R2::den + R2::num * R1::den, R1::den * R2::den&gt;</code>.
</blockquote>
<pre>
template &lt;class R1, class R2&gt; struct ratio_subtract {typedef <i>see below</i> type;};
</pre>
<blockquote>
<code>type</code> shall alias <code>ratio&lt;R1::num * R2::den - R2::num * R1::den, R1::den * R2::den&gt;</code>.
</blockquote>
<pre>
template &lt;class R1, class R2&gt; struct ratio_multiply {typedef <i>see below</i> type;};
</pre>
<blockquote>
<code>type</code> shall alias <code>ratio&lt;R1::num * R2::num, R1::den * R2::den&gt;</code>.
</blockquote>
<pre>
template &lt;class R1, class R2&gt; struct ratio_divide   {typedef <i>see below</i> type;};
</pre>
<blockquote>
<code>type</code> shall alias <code>ratio&lt;R1::num * R2::den, R2::num * R1::den&gt;</code>.
</blockquote>

</blockquote>

<h4><code>ratio</code> comparison [ratio.comparison]</h4>

<blockquote>
<pre>
template &lt;class R1, class R2&gt; struct ratio_equal
  : public integral_constant&lt;bool, <i>see below</i>&gt; {};
</pre>
<blockquote>
If <code>R1::num == R2::num &amp;&amp; R1::den == R2::den</code>,
<code>ratio_equal</code> derives from <code>true_type</code>, else
derives from <code>false_type</code>.
</blockquote>
<pre>
template &lt;class R1, class R2&gt; struct ratio_less
  : public integral_constant&lt;bool, <i>see below</i>&gt; {};
</pre>
<blockquote>
If <code>R1::num * R2::den &lt; R2::num * R1::den</code>,
<code>ratio_less</code> derives from <code>true_type</code>, else
derives from <code>false_type</code>.  Implementations are permitted
to use more complex algorithms to compute the above relationship to
avoid overflow.  If the implementation is not able to avoid overflow,
a diagnostic shall be emitted.
</blockquote>
<pre>
template &lt;class R1, class R2&gt; struct ratio_not_equal
  : public integral_constant&lt;bool, !ratio_equal&lt;R1, R2&gt;::value&gt; {}; 

template &lt;class R1, class R2&gt; struct ratio_less_equal
  : public integral_constant&lt;bool, !ratio_less&lt;R2, R1&gt;::value&gt; {};

template &lt;class R1, class R2&gt; struct ratio_greater
  : public integral_constant&lt;bool, ratio_less&lt;R2, R1&gt;::value&gt; {};

template &lt;class R1, class R2&gt; struct ratio_greater_equal
  : public integral_constant&lt;bool, !ratio_less&lt;R1, R2&gt;::value&gt; {};
</pre>

</blockquote>

<h4><code>ratio</code> SI typedefs [ratio.si]</h4>

<blockquote>
Four of the typedefs in the synopsis are conditionally supported: <code>yocto</code>, <code>zepto</code>, 
<code>zetta</code> and <code>yotta</code>.  If the constants specified in the synopsis are representable
by <code>intmax_t</code>, the typedef shall be supported as shown in the synopsis, otherwise it shall not.
</blockquote>

</blockquote>

<h2><a name="duration"></a><code>duration</code></h2>

<p>
The <code>duration</code> is the heart of this proposal.  The interface that the user will
see in everyday use is nearly identical to that of boost time durations authored by Jeff Garland,
both in syntax and in behavior.  This has been a very popular boost library for 7 years.  There
is an <b>enormous</b> <i>positive</i> history with this interface.
</p>

<p>
The library consists of six units of time duration:
</p>

<ul>
<li><code>hours</code></li>
<li><code>minutes</code></li>
<li><code>seconds</code></li>
<li><code>milliseconds</code></li>
<li><code>microseconds</code></li>
<li><code>nanoseconds</code></li>
</ul>

<p>
These units were chosen as a subset of the boost library because they are the most common units used when
sleeping, waiting on a condition variable, or waiting to obtain the lock on a mutex.  Each of these units
is nothing but a thin wrapper around a signed integral count.  That is, when you construct <code>minutes(3)</code>,
all that happens is a <code>3</code> is stored inside of <code>minutes</code>.  When you construct
<code>microseconds(3)</code>, all that happens is a <code>3</code> is stored inside of <code>microseconds</code>.
</p>

<p>
The only context in which these different types differ is when being
converted to one another.  At this time, unit-specific compile-time
conversion constants are used to convert the source unit to the target
unit.  Only conversions from coarser units to finer units are allowed
(in boost).  This restriction ensures that all conversions are always
exact.  That is, <code>microseconds</code> can always represent any
value <code>minutes</code> has.
</p>

<p>
In the boost library, these units are united via inheritance.  This paper instead unites these
units through the class template <code>duration</code>.  That is, in this proposal all six of
the above units are nothing but <code>typedef</code>s to different instantiations of <code>duration</code>.
This change from the boost library has a far reaching positive impact, while not changing the syntax of
the everyday use at all.
</p>

<p>
The most immediate positive impact is that the library can immediately generate any unit, any precision it
needs.  This is sometimes necessary when doing comparisons or arithmetic between <code>duration</code>s of
differing precision, assuming one wants the comparison and arithmetic to be exactly correct.
</p>

<p>
A secondary benefit is that by publishing the class template <code>duration</code> interface, user
code can very easily create <code>durations</code> with any precision they desire.  The <code>ratio</code>
utility is used to specify the precision, so as long as the precision can be expressed by a rational constant
with respect to seconds, this framework can <i>exactly</i> represent it (one third of a second is no problem,
and neither is one third of a femto second).  All of this utility and flexibility comes at no cost just by
making use of the no-run-time-overhead <code>ratio</code> facility.
</p>

<p>
In the boost library, <code>hours</code> does not have the same representation as <code>nanoseconds</code>.
The former is usually represented with a <code>long</code> whereas a <code>long long</code> is required
for the latter.  The reason for this is simply range.  You don't need many <code>hours</code> to cover
an extremely large range of time.  But this isn't true of <code>nanoseconds</code>.  Being able to
reduce the <code>sizeof</code> overhead for some units when possible, can be a significant performance
advantage.
</p>

<p>
This proposal continues, and generalizes that philosophy.  Not only can one specify the precision of
a <code>duration</code>, one can also specify its representation.  This can be any integral type,
or even a floating point type.  Or it can be a user-defined type which emulates an arithmetic type.
The six predefined units all use signed integral types as their representation.  And they all have a
minimum range of +/- 292 years.  <code>nanoseconds</code> needs 64 bits to cover that range.  <code>hours</code>
needs only 23 bits to cover that range.
</p>

<h3>So What Exactly is a <code>duration</code> and How Do I Use One?</h3>

<p>
A <code>duration</code> has a representation and a tick period (precision).
</p>

<blockquote><pre>
template &lt;class Rep, class Period = ratio&lt;1&gt;&gt; class duration;
</pre></blockquote>

<p>
The representation is
simply any arithmetic type, or an emulation of such a type.  The representation stores a
count of ticks.  This count is the only data member stored in a <code>duration</code>.  If the
representation is floating point, it can store fractions of a tick to the precision of the
representation.  The tick period is represented by a <code>ratio</code> and is encoded into
the <code>duration</code>'s type, instead of stored.  The tick period only has an impact on
the behavior of the <code>duration</code> when a conversion between different <code>duration</code>'s
is attempted.  The tick period is completely ignored when simply doing arithmetic among like
<code>duration</code>s.
</p>

<p>
Example:
</p>

<blockquote><pre>
typedef duration&lt;long, ratio&lt;60&gt;&gt; minutes;
minutes m1(3);                 // m1 stores 3
minutes m2(2);                 // m2 stores 2
minutes m3 = m1 + m2;          // m3 stores 5

typedef duration&lt;long long, micro&gt; microseconds;
microseconds us1(3);           // us1 stores 3
microseconds us2(2);           // us2 stores 2
microseconds us3 = us1 + us2;  // us3 stores 5

microseconds us4 = m3 + us3;   // us4 stores 300000005
</pre></blockquote>

<p>
In the final line of code above, there is an implicit conversion from minutes to
microseconds, resulting in a relatively large number of microseconds.
</p>

<p>
If you need to access the tick count within a <code>duration</code>, there is a member <code>count()</code>
which simply returns the stored tick count.
</p>

<blockquote><pre>
long long tc = us4.count();    // tc is 300000005
</pre></blockquote>

<p>
These <code>duration</code>s have very simple, very predictable, and very observable behavior.
After all, this is really nothing but the time tested interface of Jeff's boost time duration library
(unified with templates instead of inheritance).
</p>

<b>What happens if I assign <code>m3 + us3</code> to <code>minutes</code> instead of <code>microseconds</code>?</b>

<blockquote><pre>
minutes m4 = m3 + us3;
</pre></blockquote>

<p>
<u>Answer:</u> It won't compile.  The rationale is that implicit truncation error should not be allowed to
happen.  If this were to compile, then <code>m4</code> would hold 5, the same value as <code>m3</code>.
The value associated with <code>us3</code> has been effectively ignored.  This is similar to the problem
of assigning a <code>double</code> to an <code>int</code>:  the fractional part gets silently discarded.
</p>

<b>But what if the truncation behavior is what I want to do?</b>

<p>
<u>Answer:</u> There is a <code>duration_cast</code> facility to explicitly ask for this behavior:
</p>

<blockquote><pre>
minutes m4 = duration_cast&lt;minutes&gt;(m3 + us3);  // m4.count() == 5
</pre></blockquote>

<p>
In general, one can perform <code>duration</code> arithmetic at will.  If <code>duration_cast</code>
isn't used, and it compiles, the arithmetic is exact.  Any place one wants to override this
exact arithmetic behavior, <code>duration_cast</code> can be used to explicitly specify that desire.
The <code>duration_cast</code> has the same efficiency as the implicit conversion, and will even be
exact as often as it can.
</p>

<b>I'm trafficking in floating point <code>duration</code>s.  I don't want to deal with writing
<code>duration_cast</code> all over the place.  I'm content with the precision of my floating point
representation.</b>

<p>
<u>Answer:</u> Not a problem.  When the destination of a conversion has floating point representation,
all conversions are allowed to happen implicitly.
</p>

<blockquote><pre>
typedef duration&lt;double, ratio&lt;60&gt;&gt; dminutes;
dminutes dm4 = m3 + us3;  // dm4.count() == 5.000000083333333
</pre></blockquote>

<b>How expensive is all of this?</b>

<p>
<u>Answer:</u> If you were writing these conversions by hand, you could
not make it more efficient. The use of <code>ratio</code> ensures that
all conversion constants are simplified as much as possible at compile
time.  This usually results in the numerator or denominator of the
conversion factor simplifying to 1, and being subsequently ignored in
converting the run time values of the tick counts.
</p>

<b>Has the proposal been implemented?</b>

<p>
<u>Answer:</u> Yes.  There is a complete example implementation of this proposal, including test suite.
The <code>duration</code> part of it has a count of 99 semicolons.  This count includes
the <code>duration_cast</code> facility which handles all conversions, the <code>duration</code>
class template, with all arithmetic and comparison operators, and the six pre-defined units:
<code>hours</code>, <code>minutes</code>, <code>seconds</code>, <code>milliseconds</code>,
<code>microseconds</code> and <code>nanoseconds</code>.
</p>

<b>How complicated is it to build a function taking a duration parameter?</b>

<p>
<u>Answer:</u> There are several options open to the user:
</p>

<ol>

<li>
<p>
If the author of the function wants to accept any duration, and is willing to work
in floating point durations, he can simply use any floating point duration as the
parameter:
</p>

<blockquote><pre>
void f(duration&lt;double&gt; d)  // accept floating point seconds
{
    // d.count() == 3.e-6 when passed microseconds(3)
}

f(microseconds(3));
</pre></blockquote>
</li>

<li>
<p>
If the author of the function wants to traffic only in integral durations, and
is content with handling nothing finer than say <code>nanoseconds</code> (just
as an example), he can simply specify <code>nanoseconds</code> as the parameter:
</p>

<blockquote><pre>
void f(nanoseconds d)
{
    // d.count() == 3000 when passed microseconds(3)
}

f(microseconds(3));
</pre></blockquote>

<p>
In this design, if the client wants to pass in a floating point duration, or
a duration of finer precision than <code>nanoseconds</code>, then the client is responsible
for choosing his own rounding mode in the conversion to <code>nanoseconds</code>.
</p>

<blockquote><pre>
duration&lt;double&gt; s(1./3);  // 1/3 of a second
f(duration_cast&lt;nanoseconds&gt;(s));  // round towards zero in conversion to nanoseconds
</pre></blockquote>

<p>
In the example above, the client of <code>f</code> has chosen "round towards zero" as the
desired rounding mode to <code>nanoseconds</code>.  If the client has a <code>duration</code>
that won't exactly convert to <code>nanoseconds</code>, and fails to choose how the conversion
will take place, the compiler will refuse the call:
</p>

<blockquote><pre>
f(s);  // does not compile
</pre></blockquote>

</li>

<li>
<p>
If the author of the function wants to accept any duration, but wants to work with integral
representations <i>and</i> wants to control the rounding mode internally, then he can template
the function:
</p>

<blockquote><pre>
template &lt;class Rep, class Period&gt;
void f(duration&lt;Rep, Period&gt; d)
{
    // convert d to nanoseconds, rounding up if it is not an exact conversion
    nanoseconds ns = duration_cast&lt;nanoseconds&gt;(d);
    if (ns &lt; d)
        ++ns;
    // ns.count() == 333333334 when passed 1/3 of a floating point second
}

f(duration&lt;double&gt;(1./3));
</pre></blockquote>
</li>

<li>
<p>
If the author in the example does not want to accept floating point based durations,
he can enforce that behavior like so:
</p>

<blockquote><pre>
template &lt;class Period&gt;
void f(duration&lt;long long, Period&gt; d)
{
    // convert d to nanoseconds, rounding up if it is not an exact conversion
    nanoseconds ns = duration_cast&lt;nanoseconds&gt;(d);
    if (ns &lt; d)
        ++ns;
    // ns.count() == 333333334 when passed 333333333333 picoseconds
}

f(duration&lt;long long, pico&gt;(333333333333));  // About 1/3 of a second worth of picoseconds
</pre></blockquote>

<p>
Clients with floating point durations who want to use <code>f</code> will now have to convert to
an integral duration themselves before passing the result to <code>f</code>.
</p>

</li>
</ol>

<p>
In summary, the author of <code>f</code> has quite a bit of flexibility and control in the interface
he wants to provide his clients with, and easy options for manipulating that <code>duration</code>
internal to his function.
</p>

<b>Is it possible for the user to pass a duration to a function with the units being ambiguous?</b>

<p>
<u>Answer:</u> No.  No matter which option the author of <code>f</code> chooses above, the
following client code will not compile:
</p>

<blockquote><pre>
f(3);  // Will not compile, 3 is not implicitly convertible to any duration
</pre></blockquote>

<h2><a name="Clocks"></a>Clocks</h2>

<p>
While <code>duration</code>s only have precision and representation to concern themselves,
clocks and <code>time_point</code>s are intimately related and refer to one another.  Because
clocks are simpler to explain, we will do so first without fully explaining <code>time_point</code>s.
Once clocks are introduced, it will be easier to then fill in what a <code>time_point</code> is.
</p>

<p>
A clock is a concept which bundles 3 things:
</p>

<ol>
<li>A concrete <code>duration</code> type.</li>
<li>A concrete <code>time_point</code> type.</li>
<li>A function called <code>now()</code> which returns the concrete <code>time_point</code>.</li>
</ol>

<p>
This paper proposes 3 concrete clocks:
</p>

<ol>
<li><code>system_clock</code></li>
<li><code>monotonic_clock</code></li>
<li><code>high_precision_clock</code></li>
</ol>

<p>
A given platform may not be able to supply all three of these clocks.  The user is also
able to easily create more clocks.
</p>

<p>
Given a clock named <code>Clock</code>, it will have:
</p>

<blockquote><pre>
class Clock
{
public:
    typedef <i>an arithmetic-like type</i>            rep;
    typedef <i>an instantiation of <code>ratio</code></i>          period;
    typedef std::chrono::duration&lt;rep, period&gt; duration;
    typedef std::chrono::time_point&lt;Clock&gt;     time_point;
    static const bool is_monotonic =           <i>true or false</i>;

    static time_point now();
};
</pre></blockquote>

<p>
One can get the current time from <code>Clock</code> with:
</p>

<blockquote><pre>
Clock::time_point t1 = Clock::now();
</pre></blockquote>

<p>
And one can get the time duration between two <code>time_point</code>s associated with <code>Clock</code> with:
</p>

<blockquote><pre>
Clock::duration d = t1 - Clock::now();
</pre></blockquote>

<p>
And one can specify a past or future <code>time_point</code> with:
</p>

<blockquote><pre>
Clock::time_point t2 = Clock::now() + d;
</pre></blockquote>

<p>
Note how even if a particular clock becomes obsolete, the next clock in line will have the same
API.  There is no new learning curve to come up.  The only source code changes will be simply
changing the type of the clock.  The same <code>duration</code> and <code>time_point</code>
framework continues to work as new clocks are introduced.  And multiple clocks are safely
and easily handled within the same program.
</p>

<h2><a name="time_point"></a><code>time_point</code></h2>

<p>
A <code>time_point</code> represents a point in time, as opposed to a duration of time.
Another way of saying the same thing, is that a <code>time_point</code> represents an
epoch plus or minus a <code>duration</code>.  Examples of <code>time_point</code>s include:
</p>

<ul>
<li>3 minutes after the computer booted.</li>
<li>03:14:07 UTC on Tuesday, January 19, 2038</li>
<li>20 milliseconds after I started that timer.</li>
</ul>

<p>
In each of the examples above, a different epoch is implied.  Sometimes an epoch has meaning
for several millennia.  Other times the meaning of an epoch is lost after a while (such as the
start of a timer, or when the computer booted).  However,
if two <code>time_point</code>s are known to share the same epoch, they can be subtracted,
yielding a valid <code>duration</code>, even if the definition of the epoch no longer
has meaning.
</p>

<p>
In this proposal, an epoch is a purely abstract and unspecified concept.  There is no
type representing an epoch.  It is simply an idea that relates (or doesn't) <code>time_point</code>s
to a clock, and in the case that they share a clock, <code>time_point</code>s to one another.
<code>time_point</code>s associated with different clocks are generally not interoperable unless
the relationship between the epochs associated with each clock is known.
</p>

<h3>So What Exactly is a <code>time_point</code> and How Do I Use One?</h3>

<p>
A <code>time_point</code> has a clock and a <code>duration</code>.
</p>

<blockquote><pre>
template &lt;class Clock, class Duration = typename Clock::duration&gt; class time_point;
</pre></blockquote>

<p>
The <code>time_point</code>'s clock is not stored.  It is simply embedded into the
<code>time_point</code>'s type and serves two purposes:
</p>

<ol>
<li>Because <code>time_point</code>s originating from different clocks have different types,
the compiler can be instructed to fail if incompatible <code>time_point</code>s are used
in inappropriate ways.</li>
<li>Given a <code>time_point</code>, one often needs to compare that <code>time_point</code>
to "now".  This is very simple as long as the <code>time_point</code> knows what clock
it is defined with respect to.</li>
</ol>

<p>
A <code>time_point</code>'s <code>duration</code> is stored as the only data member of
the <code>time_point</code>.  Thus <code>time_point</code>s and their corresponding <code>duration</code>
have exactly the same layout.  But they have very different meanings.  For example, it is one thing
to say I want to sleep for 3 minutes.  It is a completely different thing to say I want to sleep until
3 minutes past the time I started that timer (unless you just happened to start that timer now).
Both meanings (and options for sleeping) have great practical value in common use cases for
sleeping, waiting on a condition variable, and waiting for a mutex's lock.  These same concepts and
tools are found (for example) in Ada.
</p>

<p>
A timer example:
</p>

<blockquote><pre>
void f()
{
    monotonic_clock::time_point start = monotonic_clock::now();
    g();
    h();
    duration&lt;double&gt; sec = monotonic_clock::now() - start;
    cout &lt;&lt; "f() took " &lt;&lt; sec.count() &lt;&lt; " seconds\n";
}
</pre></blockquote>

<p>
Note that if one is using the <code>duration</code> between two clock <code>time_point</code>s in a way
where the precision of the <code>duration</code> matters, it is good practice to convert the clock's
native <code>duration</code> to a known duration.  This insulates the code from future changes which
may be made to the clock's native precision in the future.
For example <code>monotonic_clock</code> could easily be based on the clock speed of the cpu.
When you upgrade to a faster machine, you do not want your code that assumed a certain tick period
of this clock to start experiencing run time failures because your timing code has silently changed
meaning.
</p>

<p>
A delay loop example:
</p>

<blockquote><pre>
// delay for at least 500 nanoseconds:
auto go = monotonic_clock::now() + nanoseconds(500);
while (monotonic_clock::now() &lt; go)
    ;
</pre></blockquote>

<p>
The above code will delay as close as possible to half a microsecond, no matter what the precision
of <code>monotonic_clock</code> is.  The more precise <code>monotonic_clock</code> becomes, the
more accurate will be the delay to 500 nanoseconds.
</p>

<h3><a name="time_wording"></a>Time Proposed Wording</h3>

<p>
Add a new subsection to 20.7 [date.time]:
</p>

<blockquote>
<h4>Time utilities [time]</h4>

<p>
This subclause contains generally useful time utilities, also used in section 30 [thread].
</p>

<h5>Header &lt;chrono&gt; synopsis  [chrono.synop]</h5>

<blockquote><pre>
namespace std {
namespace chrono {

template &lt;class Rep, class Period = ratio&lt;1&gt;&gt; class duration;
template &lt;class Clock, class Duration = typename Clock::duration&gt; class time_point;

}  <i>// namespace chrono</i>

<i>// common_type traits</i>
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
  struct common_type&lt;chrono::duration&lt;Rep1, Period1&gt;, chrono::duration&lt;Rep2, Period2&gt;&gt;;

template &lt;class Clock, class Duration1, class Duration2&gt;
  struct common_type&lt;chrono::time_point&lt;Clock, Duration1&gt;, chrono::time_point&lt;Clock, Duration2&gt;&gt;;

namespace chrono {

<i>// customization traits</i>
template &lt;class Rep&gt; struct treat_as_floating_point;
template &lt;class Rep&gt; struct duration_values;

<i>// duration arithmetic</i>
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
  typename common_type&lt;duration&lt;Rep1, Period1&gt;, duration&lt;Rep2, Period2&gt;&gt;::type
  operator+(const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
  typename common_type&lt;duration&lt;Rep1, Period1&gt;, duration&lt;Rep2, Period2&gt;&gt;::type
  operator-(const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
template &lt;class Rep1, class Period, class Rep2&gt;
  duration&lt;typename common_type&lt;Rep1, Rep2&gt;::type, Period&gt;
  operator*(const duration&lt;Rep1, Period&gt;&amp; d, const Rep2&amp; s);
template &lt;class Rep1, class Period, class Rep2&gt;
  duration&lt;typename common_type&lt;Rep1, Rep2&gt;::type, Period&gt;
  operator*(const Rep1&amp; s, const duration&lt;Rep2, Period&gt;&amp; d);
template &lt;class Rep1, class Period, class Rep2&gt;
  duration&lt;typename common_type&lt;Rep1, Rep2&gt;::type, Period&gt;
  operator/(const duration&lt;Rep1, Period&gt;&amp; d, const Rep2&amp; s);
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
  typename common_type&lt;Rep1, Rep2&gt;::type
  operator/(const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);

<i>// duration comparisons</i>
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
   bool operator==(const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
   bool operator!=(const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
   bool operator&lt; (const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
   bool operator&lt;=(const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
   bool operator&gt; (const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
   bool operator&gt;=(const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);

<i>// duration_cast</i>
template &lt;class ToDuration, class Rep, class Period&gt;
  ToDuration duration_cast(const duration&lt;Rep, Period&gt;&amp; d);

<i>// convenience typedefs</i>
typedef duration&lt;<i>signed integral type of at least 64 bits</i>,        nano&gt; nanoseconds;
typedef duration&lt;<i>signed integral type of at least 55 bits</i>,       micro&gt; microseconds;
typedef duration&lt;<i>signed integral type of at least 45 bits</i>,       milli&gt; milliseconds;
typedef duration&lt;<i>signed integral type of at least 35 bits</i>             &gt; seconds;
typedef duration&lt;<i>signed integral type of at least 29 bits</i>, ratio&lt;  60&gt;&gt; minutes;
typedef duration&lt;<i>signed integral type of at least 23 bits</i>, ratio&lt;3600&gt;&gt; hours;

<i>// time_point arithmetic</i>
template &lt;class Clock, class Duration1, class Rep2, class Period2&gt;
  time_point&lt;Clock, typename common_type&lt;Duration1, duration&lt;Rep2, Period2&gt;&gt;::type&gt;
  operator+(const time_point&lt;Clock, Duration1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
template &lt;class Rep1, class Period1, class Clock, class Duration2&gt;
  time_point&lt;Clock, typename common_type&lt;duration&lt;Rep1, Period1&gt;, Duration2&gt;::type&gt;
  operator+(const duration&lt;Rep1, Period1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);
template &lt;class Clock, class Duration1, class Rep2, class Period2&gt;
  time_point&lt;Clock, typename common_type&lt;Duration1, duration&lt;Rep2, Period2&gt;&gt;::type&gt;
  operator-(const time_point&lt;Clock, Duration1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
template &lt;class Clock, class Duration1, class Duration2&gt;
  typename common_type&lt;Duration1, Duration2&gt;::type
  operator-(const time_point&lt;Clock, Duration1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);

<i>// time_point comparisons</i>
template &lt;class Clock, class Duration1, class Duration2&gt;
   bool operator==(const time_point&lt;Clock, Duration1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);
template &lt;class Clock, class Duration1, class Duration2&gt;
   bool operator!=(const time_point&lt;Clock, Duration1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);
template &lt;class Clock, class Duration1, class Duration2&gt;
   bool operator&lt; (const time_point&lt;Clock, Duration1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);
template &lt;class Clock, class Duration1, class Duration2&gt;
   bool operator&lt;=(const time_point&lt;Clock, Duration1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);
template &lt;class Clock, class Duration1, class Duration2&gt;
   bool operator&gt; (const time_point&lt;Clock, Duration1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);
template &lt;class Clock, class Duration1, class Duration2&gt;
   bool operator&gt;=(const time_point&lt;Clock, Duration1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);

<i>// time_point_cast</i>

template &lt;class ToDuration, class Clock, class Duration&gt;
  time_point&lt;Clock, ToDuration&gt; time_point_cast(const time_point&lt;Clock, Duration&gt;&amp; t);

<i>// Clocks</i>
class system_clock;
class monotonic_clock;
class high_resolution_clock;

}  <i>// namespace chrono</i>
}  <i>// namespace std</i>
</pre></blockquote>

<h5>Clock Requirements  [chrono.clock.req]</h5>

<p>
A clock represents a bundle consisting of a native <code>duration</code>, a native <code>time_point</code>, and
a function <code>now()</code> to get the current <code>time_point</code>.  A clock shall meet the requirements in
Table ?.
</p>

<p>
In Table ? <code>C1</code> and <code>C2</code> denote clock types.  <code>t1</code> and <code>t2</code> are values
returned from <code>C1::now()</code> where the call returning <code>t1</code> happens before [intro.multithread]
the call returning <code>t2</code> and both of these calls happen before <code>C1::time_point::max()</code>.
</p>

<table border="1">
<caption>Table ?: Clock Requirements</caption>
<tr>
<th>expression</th>
<th>return type</th>
<th>operational semantics</th>
</tr>

<tr>
<td><code>C1::rep</code></td>
<td>An arithmetic type or class emulating an arithmetic type.</td>
<td>The representation type of the native <code>duration</code> and <code>time_point</code>.</td>
</tr>

<tr>
<td><code>C1::period</code></td>
<td><code>ratio</code></td>
<td>The tick period of the clock in seconds.</td>
</tr>

<tr>
<td><code>C1::duration</code></td>
<td><code>chrono::duration&lt;C1::rep,&nbsp;C1::period&gt;</code></td>
<td>The native <code>duration</code> type of the clock.</td>
</tr>

<tr>
<td><code>C1::time_point</code></td>
<td><code>chrono::time_point&lt;C1&gt;</code> or <code>chrono::time_point&lt;C2,&nbsp;C1::duration&gt;</code></td>
<td>The native <code>time_point</code> type of the clock.
Different clocks are permitted to share a <code>time_point</code> definition if it is valid to compare
their <code>time_point</code>s by comparing their respective <code>duration</code>s.
<code>C1</code> and <code>C2</code> shall refer to the same epoch.</td>
</tr>

<tr>
<td><code>C1::is_monotonic</code></td>
<td><code>const bool</code></td>
<td>
<code>true</code> if <code>t1 &lt;= t2</code> is always <code>true</code>, else
<code>false</code>.  [<i>Note:</i> A clock that can be adjusted backwards is not monotonic. <i>-- end note</i>]
</td>

</tr>

<tr>
<td><code>C1::now()</code></td>
<td><code>C1::time_point</code></td>
<td>Returns a <code>time_point</code> representing the current point in time.</td>
</tr>

</table>

<h5>Time related traits  [chrono.traits]</h5>

<pre>
template &lt;class Rep&gt; struct treat_as_floating_point
  : is_floating_point&lt;Rep&gt; {};
</pre>

<p>
The <code>duration</code> template uses the <code>treat_as_floating_point</code> trait to help
determine if a <code>duration</code> with one tick <code>period</code> can be converted to
another <code>duration</code> with a different tick <code>period</code>.  If
<code>treat_as_floating_point&lt;Rep&gt;::value</code> is <code>true</code>, then <code>Rep</code>
is a floating point type and implicit conversions are allowed among <code>duration</code>s.
Otherwise, the implicit convertibility depends on the tick <code>period</code>s of the
<code>duration</code>s.  If <code>Rep</code> is a class type which emulates a floating point
type, the author of <code>Rep</code>
can specialize <code>treat_as_floating_point</code> so that <code>duration</code> will treat
this <code>Rep</code> as if it were a floating point type.  Otherwise <code>Rep</code> is
assumed to be an integral type, or a class emulating an integral type.
</p>

<pre>
template &lt;class Rep&gt;
struct duration_values
{
public:
    static constexpr Rep zero();
    static constexpr Rep max();
    static constexpr Rep min();
};
</pre>

<p>
The <code>duration</code> template uses the <code>duration_values</code> trait to construct
special values of the <code>duration</code>s representation (<code>Rep</code>).  This is done
because the representation might be a class type with behavior which requires some other
implementation to return these special values.  In that case, the author of that class type
should specialize <code>duration_values</code> to return the indicated values.
</p>

<pre>
static constexpr Rep zero();
</pre>

<blockquote>
<p>
<i>Returns:</i> <code>Rep(0)</code>.
[<i>Note:</i> <code>Rep(0)</code> is specified instead of <code>Rep()</code> since <code>Rep()</code>
may have some other meaning, such as an uninitialized value. <i>-- end note</i>]
</p>
<p>
<i>Remarks</i>:  The value returned shall correspond to the additive identity.
</p>
</blockquote>

<pre>
static constexpr Rep max();
</pre>

<blockquote>
<p>
<i>Returns:</i> <code>numeric_limits&lt;Rep&gt;::max()</code>.
</p>
<p>
<i>Remarks</i>:  The value returned shall compare greater than <code>zero()</code>.
</p>
</blockquote>

<pre>
static constexpr Rep min();
</pre>

<blockquote>
<p>
<i>Returns:</i> <code>numeric_limits&lt;Rep&gt;::lowest()</code>.
</p>
<p>
<i>Remarks</i>:  The value returned shall compare less than or equal to <code>zero()</code>.
</p>
</blockquote>

<h5><code>common_type</code> specializations</h5>

<pre>
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
struct common_type&lt;chrono::duration&lt;Rep1, Period1&gt;, chrono::duration&lt;Rep2, Period2&gt;&gt;
{
    typedef chrono::duration&lt;typename common_type&lt;Rep1, Rep2&gt;::type, <i>see below</i>&gt; type;
};
</pre>

<p>
The <code>period</code> of the <code>duration</code> indicated by this specialization of <code>common_type</code>
shall be the greatest common divisor of <code>Period1</code> and <code>Period2</code>.  This can be computed by
forming a <code>ratio</code> of the greatest common divisor of <code>Period1::num</code> and <code>Period2::num</code>,
and the least common multiple of <code>Period1::den</code> and <code>Period2::den</code>.
</p>

<p>
<i>Note:</i> The <code>typedef type</code> is the <code>duration</code> with the largest tick <code>period</code>
possible where both <code>duration</code> arguments will convert to it without requiring a division operation.
The representation of this type is intended to be able to hold any value resulting from this conversion, with the
possible exception of round-off error when floating point <code>duration</code>s are involved (but not truncation
error).
</p>

<pre>
template &lt;class Clock, class Duration1, class Duration2&gt;
struct common_type&lt;chrono::time_point&lt;Clock, Duration1&gt;, chrono::time_point&lt;Clock, Duration2&gt;&gt;
{
    typedef chrono::time_point&lt;Clock, typename common_type&lt;Duration1, Duration2&gt;::type&gt; type;
};
</pre>

<p>
The <code>common_type</code> of two <code>time_point</code>s is a <code>time_point</code> with the same clock (both
shall have the same clock), and the <code>common_type</code> of the two <code>duration</code>s.
</p>

<h5>Class template <code>duration</code>  [chrono.duration]</h5>

<p>
A <code>duration</code> measures time between two points in time (<code>time_point</code>).
A <code>duration</code> has a representation which holds a count of ticks, and a tick period.  The tick period
is the amount of time which occurs from one tick to another in units of a second.  It is expressed as a rational
constant using <code>ratio</code>.
</p>

<pre>
template &lt;class Rep, class Period = ratio&lt;1&gt;&gt;
class duration
{
public:
    typedef Rep    rep;
    typedef Period period;
private:
    rep rep_;  // exposition only
public:
    // construction / destruction
    duration() = default;
    template &lt;class Rep2&gt;
        explicit duration(const Rep2&amp; r);
    ~duration() = default;

    // copy semantics
    duration(const duration&amp;) = default;
    duration&amp; operator=(const duration&amp;) = default;

    // conversions
    template &lt;class Rep2, class Period2&gt;
       duration(const duration&lt;Rep2, Period2&gt;&amp; d);

    // observer

    rep count() const;

    // arithmetic

    duration  operator+() const;
    duration  operator-() const;
    duration&amp; operator++();
    duration  operator++(int);
    duration&amp; operator--();
    duration  operator--(int);

    duration&amp; operator+=(const duration&amp; d);
    duration&amp; operator-=(const duration&amp; d);

    duration&amp; operator*=(const rep&amp; rhs);
    duration&amp; operator/=(const rep&amp; rhs);

    // special values

    static constexpr duration zero();
    static constexpr duration min();
    static constexpr duration max();
};
</pre>

<p>
<code>Rep</code> shall be an arithmetic type, or a class emulating an
arithmetic type.  If <code>duration</code> is instantiated with the type of <code>Rep</code>
being a <code>duration</code>, a diagnostic is required.
</p>

<p>
<code>Period</code> shall be an instantiation of <code>ratio</code>, diagnostic required.
</p>

<p>
<code>Period::num</code> shall be positive, diagnostic required.
</p>

<p>
Examples:
</p>

<blockquote>
<p>
<code>duration&lt;long, ratio&lt;60&gt;&gt;</code> holds a count of minutes using a <code>long</code>.
<p>
<p>
<code>duration&lt;long long, milli&gt;</code> holds a count of milliseconds using a <code>long long</code>.
<p>
<p>
<code>duration&lt;double, ratio&lt;1, 30&gt;&gt;</code> holds a count using a <code>double</code> with
a tick period of 1/30 second (a tick frequency of 30 Hz).
<p>
</blockquote>

<p>
The following members of <code>duration</code> do not throw an exception
unless the indicated operations on the representations throw an
exception.
</p>

<h5><code>duration</code> constructors</h5>

<pre>
template &lt;class Rep2&gt;
    explicit duration(const Rep2&amp; r);
</pre>

<blockquote>
<p>
<i>Requires:</i> <code>Rep2</code> is implicitly convertible to <code>rep</code>, and
</p>
<ul>
<li><code>treat_as_floating_point&lt;rep&gt;::value</code> is <code>true</code>, or</li>
<li><code>!treat_as_floating_point&lt;rep&gt;::value &amp;&amp; !treat_as_floating_point&lt;Rep2&gt;::value</code> is <code>true</code>.
</ul>
<p>
A diagnostic is required if this requirement is not met. [<i>Note:</i> This requirement prevents
construction of an integral-based <code>duration</code> with a floating point representation.  Such
a construction could easily lead to confusion about the value of the <code>duration</code>.
<i>-- end note</i>]
</p>
<p>
Example:
</p>
<blockquote><pre>
duration&lt;int, milli&gt; d(3.5);  // shall not compile
duration&lt;int, milli&gt; d(3);    // ok
</pre></blockquote>

<p>
<i>Effects:</i> Constructs an object of type <code>duration</code>.
</p>

<p>
<i>PostConditions:</i> <code>count() == static_cast&lt;rep&gt;(r)</code>.
</p>
</blockquote>

<pre>
template &lt;class Rep2, class Period2&gt;
   duration(const duration&lt;Rep2, Period2&gt;&amp; d);
</pre>

<blockquote>
<p>
<i>Requires:</i> <code>treat_as_floating_point&lt;rep&gt;::value</code>, or
<code>ratio_divide&lt;Period2, period&gt;::type::den == 1</code>.
</p>
<p>
A diagnostic is required if this requirement is not met. [<i>Note:</i> This requirement prevents
implicit truncation error when converting between integral-based <code>duration</code>s.  Such
a construction could easily lead to confusion about the value of the <code>duration</code>.
<i>-- end note</i>]
</p>
<p>
Example:
</p>
<blockquote><pre>
duration&lt;int, milli&gt; ms(3);
duration&lt;int, micro&gt; us = ms;  // ok
duration&lt;int, milli&gt; ms2 = us; // shall not compile
</pre></blockquote>

<p>
<i>Effects:</i> Constructs an object of type <code>duration</code>, constructing
<code>rep_</code> from <code>duration_cast&lt;duration&gt;(d).count()</code>.
</p>
</blockquote>

<h5><code>duration</code> observers</h5>

<pre>
rep count() const;
</pre>

<blockquote>
<p>
<i>Returns:</i> <code>rep_</code>.
</p>
</blockquote>

<h5><code>duration</code> member arithmetic</h5>

<pre>
duration operator+() const;
</pre>

<blockquote>
<p>
<i>Returns:</i> <code>*this</code>.
</p>
</blockquote>

<pre>
duration operator-() const;
</pre>

<blockquote>
<p>
<i>Returns:</i> <code>duration(-rep_)</code>.
</p>
</blockquote>

<pre>
duration&amp; operator++();
</pre>

<blockquote>
<p>
<i>Effects:</i> <code>++rep_</code>.
</p>
<p>
<i>Returns:</i> <code>*this</code>.
</p>
</blockquote>

<pre>
duration operator++(int);
</pre>

<blockquote>
<p>
<i>Returns:</i> <code>duration(rep_++)</code>.
</p>
</blockquote>

<pre>
duration&amp; operator--();
</pre>

<blockquote>
<p>
<i>Effects:</i> <code>--rep_</code>.
</p>
<p>
<i>Returns:</i> <code>*this</code>.
</p>
</blockquote>

<pre>
duration operator--(int);
</pre>

<blockquote>
<p>
<i>Returns:</i> <code>duration(rep_--)</code>.
</p>
</blockquote>

<pre>
duration&amp; operator+=(const duration&amp; d);
</pre>

<blockquote>
<p>
<i>Effects:</i> <code>rep_ += d.count()</code>.
</p>
<p>
<i>Returns:</i> <code>*this</code>.
</p>
</blockquote>

<pre>
duration&amp; operator-=(const duration&amp; d);
</pre>

<blockquote>
<p>
<i>Effects:</i> <code>rep_ -= d.count()</code>.
</p>
<p>
<i>Returns:</i> <code>*this</code>.
</p>
</blockquote>

<pre>
duration&amp; operator*=(const rep&amp; rhs);
</pre>

<blockquote>
<p>
<i>Effects:</i> <code>rep_ *= rhs</code>.
</p>
<p>
<i>Returns:</i> <code>*this</code>.
</p>
</blockquote>

<pre>
duration&amp; operator/=(const rep&amp; rhs);
</pre>

<blockquote>
<p>
<i>Effects:</i> <code>rep_ /= rhs</code>.
</p>
<p>
<i>Returns:</i> <code>*this</code>.
</p>
</blockquote>

<h5><code>duration</code> special values</h5>

<pre>
static constexpr duration zero();
</pre>

<blockquote>
<p>
<i>Returns:</i> <code>duration(duration_values&lt;rep&gt;::zero())</code>.
</p>
</blockquote>

<pre>
static constexpr duration min();
</pre>

<blockquote>
<p>
<i>Returns:</i> <code>duration(duration_values&lt;rep&gt;::min())</code>.
</p>
</blockquote>

<pre>
static constexpr duration max();
</pre>

<blockquote>
<p>
<i>Returns:</i> <code>duration(duration_values&lt;rep&gt;::max())</code>.
</p>
</blockquote>

<h5><code>duration</code> non-member arithmetic</h5>

<pre>
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
  typename common_type&lt;duration&lt;Rep1, Period1&gt;, duration&lt;Rep2, Period2&gt;&gt;::type
  operator+(const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>CD(lhs) += rhs</code> where <code>CD</code> is the type of the return value.
</blockquote>

<pre>
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
  typename common_type&lt;duration&lt;Rep1, Period1&gt;, duration&lt;Rep2, Period2&gt;&gt;::type
  operator-(const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>CD(lhs) -= rhs</code> where <code>CD</code> is the type of the return value.
</blockquote>

<pre>
template &lt;class Rep1, class Period, class Rep2&gt;
  duration&lt;typename common_type&lt;Rep1, Rep2&gt;::type, Period&gt;
  operator*(const duration&lt;Rep1, Period&gt;&amp; d, const Rep2&amp; s);
</pre>

<blockquote>
<p>
<i>Requires:</i> Let <code>CR</code> represent the <code>common_type</code> of <code>Rep1</code>
and <code>Rep2</code>.  Both <code>Rep1</code> and <code>Rep2</code> shall be implicitly
convertible to <code>CR</code>, diagnostic required.
</p>

<p>
<i>Returns:</i> <code>duration&lt;CR, Period>(d) *= s</code>.
</p>
</blockquote>

<pre>
template &lt;class Rep1, class Period, class Rep2&gt;
  duration&lt;typename common_type&lt;Rep1, Rep2&gt;::type, Period&gt;
  operator*(const Rep1&amp; s, const duration&lt;Rep2, Period&gt;&amp; d);
</pre>

<blockquote>
<p>
<i>Requires:</i> Let <code>CR</code> represent the <code>common_type</code> of <code>Rep1</code>
and <code>Rep2</code>.  Both <code>Rep1</code> and <code>Rep2</code> shall be implicitly
convertible to <code>CR</code>, diagnostic required.
</p>

<p>
<i>Returns:</i> <code>d * s</code>.
</p>
</blockquote>

<pre>
template &lt;class Rep1, class Period, class Rep2&gt;
  duration&lt;typename common_type&lt;Rep1, Rep2&gt;::type, Period&gt;
  operator/(const duration&lt;Rep1, Period&gt;&amp; d, const Rep2&amp; s);
</pre>

<blockquote>
<p>
<i>Requires:</i> Let <code>CR</code> represent the <code>common_type</code> of <code>Rep1</code>
and <code>Rep2</code>.  Both <code>Rep1</code> and <code>Rep2</code> shall be implicitly
convertible to <code>CR</code>, and <code>Rep2</code> shall not be an instantiation of <code>duration</code>,
diagnostic required.
</p>

<p>
<i>Returns:</i> <code>duration&lt;CR, Period>(d) /= s</code>.
</p>
</blockquote>

<pre>
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
  typename common_type&lt;Rep1, Rep2&gt;::type
  operator/(const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
</pre>

<blockquote>
<p>
<i>Returns:</i> Let <code>CD</code> represent the <code>common_type</code> of the two
<code>duration</code> arguments.  Returns <code>CD(lhs).count() / CD(rhs).count()</code>.
</p>
</blockquote>

<h5><code>duration</code> comparisons</h5>

<pre>
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
   bool operator==(const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> Let <code>CD</code> represent the <code>common_type</code> of the two
<code>duration</code> arguments.  Returns <code>CD(lhs).count() == CD(rhs).count()</code> 
</blockquote>

<pre>
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
   bool operator!=(const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>!(lhs == rhs)</code>.
</blockquote>

<pre>
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
   bool operator&lt; (const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> Let <code>CD</code> represent the <code>common_type</code> of the two
<code>duration</code> arguments.  Returns <code>CD(lhs).count() &lt; CD(rhs).count()</code> 
</blockquote>

<pre>
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
   bool operator&lt;=(const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>!(rhs &lt; lhs)</code>.
</blockquote>

<pre>
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
   bool operator&gt; (const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>rhs &lt; lhs</code>.
</blockquote>

<pre>
template &lt;class Rep1, class Period1, class Rep2, class Period2&gt;
   bool operator&gt;=(const duration&lt;Rep1, Period1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>!(lhs &lt; rhs)</code>.
</blockquote>

<h5><code>duration_cast</code></h5>

<pre>
template &lt;class ToDuration, class Rep, class Period&gt;
  ToDuration duration_cast(const duration&lt;Rep, Period&gt;&amp; d);
</pre>

<blockquote>
<p>
<i>Requires:</i> <code>ToDuration</code> is an instantiation of <code>duration</code>, diagnostic required.
</p>
<p>
<i>Returns:</i> Forms <code>CF</code> which is a <code>ratio</code> resulting from
<code>ratio_divide&lt;Period, typename ToDuration::period&gt;::type</code>.
Let <code>CR</code> be the <code>common_type</code> of
<code>ToDuration::rep</code>, <code>Rep</code>, and <code>intmax_t</code>.
</p>

<ul>
<li>
<p>
If <code>CF::num == 1</code> and <code>CF::den == 1</code>, then returns
</p>
<blockquote>
<code>ToDuration(static_cast&lt;typename ToDuration::rep&gt;(d.count()))</code>
</blockquote>
</li>
<li>
<p>
else if <code>CF::num != 1</code> and <code>CF::den == 1</code>, then returns
</p>
<blockquote>
<pre>ToDuration(static_cast&lt;typename ToDuration::rep&gt;(static_cast&lt;CR&gt;(d.count()) *
                                                 static_cast&lt;CR&gt;(CF::num)))</pre>
</blockquote>
</li>
<li>
<p>
else if <code>CF::num == 1</code> and <code>CF::den != 1</code>, then returns
</p>
<blockquote>
<pre>ToDuration(static_cast&lt;typename ToDuration::rep&gt;(static_cast&lt;CR&gt;(d.count()) /
                                                 static_cast&lt;CR&gt;(CF::den)))</pre>
</blockquote>
</li>
<li>
<p>
else returns
</p>
<blockquote>
<pre>ToDuration(static_cast&lt;typename ToDuration::rep&gt;(static_cast&lt;CR&gt;(d.count()) *
                                                 static_cast&lt;CR&gt;(CF::num)   /
                                                 static_cast&lt;CR&gt;(CF::den)))</pre>
</blockquote>
</li>
</ul>

<p>
<i>Remarks:</i> This function shall not rely on any implicit conversions.  All conversions shall be accomplished through
<code>static_cast</code>.  The implementation shall avoid all multiplications or divisions when it is known at
compile time that it can be avoided because one or more arguments are 1.  All intermediate computations shall be carried
out in the widest possible representation and only converted to the destination representation at the final step.
</p>
</blockquote>

<h5>Class template <code>time_point</code>  [chrono.time.point]</h5>

<p>
A <code>time_point</code> represents a point in time with respect to a specific clock.
</p>

<h5>Class template <code>time_point</code></h5>

<pre>
template &lt;class Clock, class Duration = typename Clock::duration&gt;
class time_point
{
public:
    typedef Clock                     clock;
    typedef Duration                  duration;
    typedef typename duration::rep    rep;
    typedef typename duration::period period;
private:
    duration d_;  // exposition only

public:
    time_point();  // has value "epoch"
    explicit time_point(const duration&amp; d);  // same as time_point() + d

    // conversions
    template &lt;class Duration2&gt;
       time_point(const time_point&lt;clock, Duration2&gt;&amp; t);

    // observer

    duration time_since_epoch() const;

    // arithmetic

    time_point&amp; operator+=(const duration&amp; d);
    time_point&amp; operator-=(const duration&amp; d);

    // special values

    static constexpr time_point min();
    static constexpr time_point max();
};
</pre>

<p>
<code>Clock</code> shall meet the Clock Requirements [chrono.clock.req].
</p>

<p>
<code>Duration</code> shall be an instantiation of <code>duration</code>, diagnostic required.
</p>

<h5><code>time_point</code> constructors</h5>

<pre>
time_point();
</pre>

<blockquote>
<i>Effects:</i> Constructs an object of <code>time_point</code>, initializing <code>d_</code> with
<code>duration::zero()</code>.  This <code>time_point</code> represents the epoch.
</blockquote>

<pre>
time_point(const duration&amp; d);
</pre>

<blockquote>
<i>Effects:</i> Constructs an object of <code>time_point</code>, initializing <code>d_</code> with
<code>d</code>.  This <code>time_point</code> represents the epoch <code>+ d</code>.
</blockquote>

<pre>
template &lt;class Duration2&gt;
   time_point(const time_point&lt;clock, Duration2&gt;&amp; t);
</pre>

<blockquote>
<p>
<i>Requires:</i> <code>Duration2</code> shall be implicitly convertible to <code>duration</code>, diagnostic
required.
</p>

<p>
<i>Effects:</i> Constructs an object of <code>time_point</code>, initializing <code>d_</code> with
<code>t.time_since_epoch()</code>.
</p>
</blockquote>

<h5><code>time_point</code> observers</h5>

<pre>
duration time_since_epoch() const;
</pre>

<blockquote>
<p>
<i>Returns:</i> <code>d_</code>.
</p>
</blockquote>

<h5><code>time_point</code> member arithmetic</h5>

<pre>
time_point&amp; operator+=(const duration&amp; d);
</pre>

<blockquote>
<p>
<i>Effects:</i> <code>d_ += d</code>.
</p>
<p>
<i>Returns:</i> <code>*this</code>.
</p>
</blockquote>

<pre>
time_point&amp; operator-=(const duration&amp; d);
</pre>

<blockquote>
<p>
<i>Effects:</i> <code>d_ -= d</code>.
</p>
<p>
<i>Returns:</i> <code>*this</code>.
</p>
</blockquote>

<h5><code>time_point</code> special values</h5>

<pre>
static constexpr time_point min();
</pre>

<blockquote>
<i>Returns:</i> <code>time_point(duration::min())</code>.
</blockquote>

<pre>
static constexpr time_point max();
</pre>

<blockquote>
<i>Returns:</i> <code>time_point(duration::max())</code>.
</blockquote>

<h5><code>time_point</code> non-member arithmetic</h5>

<pre>
template &lt;class Clock, class Duration1, class Rep2, class Period2&gt;
  time_point&lt;Clock, typename common_type&lt;Duration1, duration&lt;Rep2, Period2&gt;&gt;::type&gt;
  operator+(const time_point&lt;Clock, Duration1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>CT(lhs) += rhs</code> where <code>CT</code> is the type of the return value.
</blockquote>

<pre>
template &lt;class Rep1, class Period1, class Clock, class Duration2&gt;
  time_point&lt;Clock, typename common_type&lt;duration&lt;Rep1, Period1&gt;, Duration2&gt;::type&gt;
  operator+(const duration&lt;Rep1, Period1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>rhs + lhs</code>.
</blockquote>

<blockquote>
</blockquote>

<pre>
template &lt;class Clock, class Duration1, class Rep2, class Period2&gt;
  time_point&lt;Clock, typename common_type&lt;Duration1, duration&lt;Rep2, Period2&gt;&gt;::type&gt;
  operator-(const time_point&lt;Clock, Duration1&gt;&amp; lhs, const duration&lt;Rep2, Period2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>lhs + (-rhs)</code>.
</blockquote>

<pre>
template &lt;class Clock, class Duration1, class Duration2&gt;
  typename common_type&lt;Duration1, Duration2&gt;::type
  operator-(const time_point&lt;Clock, Duration1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>lhs.time_since_epoch() - rhs.time_since_epoch()</code>.
</blockquote>

<h5><code>time_point</code> comparisons</h5>

<pre>
template &lt;class Clock, class Duration1, class Duration2&gt;
   bool operator==(const time_point&lt;Clock, Duration1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>lhs.time_since_epoch() == rhs.time_since_epoch()</code>.
</blockquote>

<pre>
template &lt;class Clock, class Duration1, class Duration2&gt;
   bool operator!=(const time_point&lt;Clock, Duration1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>!(lhs == rhs)</code>.
</blockquote>

<pre>
template &lt;class Clock, class Duration1, class Duration2&gt;
   bool operator&lt; (const time_point&lt;Clock, Duration1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>lhs.time_since_epoch() &lt; rhs.time_since_epoch()</code>.
</blockquote>

<pre>
template &lt;class Clock, class Duration1, class Duration2&gt;
   bool operator&lt;=(const time_point&lt;Clock, Duration1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>!(rhs &lt; lhs)</code>.
</blockquote>

<pre>
template &lt;class Clock, class Duration1, class Duration2&gt;
   bool operator&gt; (const time_point&lt;Clock, Duration1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>rhs &lt; lhs</code>.
</blockquote>

<pre>
template &lt;class Clock, class Duration1, class Duration2&gt;
   bool operator&gt;=(const time_point&lt;Clock, Duration1&gt;&amp; lhs, const time_point&lt;Clock, Duration2&gt;&amp; rhs);
</pre>

<blockquote>
<i>Returns:</i> <code>!(lhs &lt; rhs)</code>.
</blockquote>

<h5><code>time_point_cast</code></h5>

<pre>
template &lt;class ToDuration, class Clock, class Duration&gt;
  time_point&lt;Clock, ToDuration&gt; time_point_cast(const time_point&lt;Clock, Duration&gt;&amp; t);
</pre>

<blockquote>
<p>
<i>Requires:</i> <code>ToDuration</code> is an instantiation of <code>duration</code>, diagnostic required.
</p>
<p>
<i>Returns:</i> <code>time_point&lt;Clock, ToDuration&gt;(duration_cast&lt;ToDuration&gt;(t.time_since_epoch()))</code>.
</p>
</blockquote>

<h5>Clocks  [chrono.clock]</h5>

<p>
The types defined in this section shall satisfy the Clock Requirements [chrono.clock.req].
</p>

<h5><code>system_clock</code></h5>

<p>
Class <code>system_clock</code> represents wall clock time from the system-wide realtime clock.
</p>

<pre>
class system_clock
{
public:
    typedef &lt;<i>see below</i>&gt;                      rep;
    typedef ratio&lt;<i>unspecified</i>, <i>unspecified</i>&gt;  period;
    typedef chrono::duration&lt;rep, period&gt;    duration;
    typedef chrono::time_point&lt;system_clock&gt; time_point;
    static const bool is_monotonic =         &lt;<i>unspecified</i>&gt;;

    static time_point now();

    // Map to C API
    static time_t      to_time_t  (const time_point&amp; t);
    static time_point  from_time_t(time_t t);
};
</pre>

<p>
<code>system_clock::duration::min() &lt; system_clock::duration::zero()</code>
shall be <code>true</code>.
</p>

<pre>
time_t to_time_t(const time_point&amp; t);
</pre>

<blockquote>
<i>Returns:</i> A <code>time_t</code> such that the <code>time_t</code> and <code>t</code> represent the same
point in time, truncated to the courser of the precisions among <code>time_t</code> and <code>t</code>.
</blockquote>

<pre>
time_point from_time_t(time_t t);
</pre>

<blockquote>
<i>Returns:</i> A <code>time_point</code> such that the <code>time_point</code> and <code>t</code> represent the same
point in time, truncated to the courser of the precisions among <code>time_point</code> and <code>t</code>.
</blockquote>

<h5><code>monotonic_clock</code></h5>

<p>
<code>monotonic_clock</code> represents a clock for
which the <code>time_point</code> never decreases as physical time
advances.  This type is conditionally supported: if not provided,
class <code>monotonic_clock</code> shall not be
declared. <code>monotonic_clock</code> is permitted to be a separate type or 
a <code>typedef</code> of <code>system_clock</code>.
</p>

<pre>
class monotonic_clock
{
public:
    typedef &lt;<i>unspecified</i>&gt;                             rep;
    typedef ratio&lt;<i>unspecified</i>, <i>unspecified</i>&gt;           period;
    typedef chrono::duration&lt;rep, period&gt;             duration;
    typedef chrono::time_point&lt;<i>unspecified, duration</i>&gt; time_point;
    static const bool is_monotonic =                  true;

    static time_point now();
};
</pre>

<h5><code>high_resolution_clock</code></h5>

<p>
Class <code>high_resolution_clock</code> represents the clock with the shortest tick
<code>period</code>. <code>high_resolution_clock</code> is permitted to be a separate type or 
a <code>typedef</code> of <code>system_clock</code> or <code>monotonic_clock</code>.
</p>

<pre>
class high_resolution_clock
{
public:
    typedef &lt;<i>unspecified</i>&gt;                             rep;
    typedef ratio&lt;<i>unspecified</i>, <i>unspecified</i>&gt;           period;
    typedef chrono::duration&lt;rep, period&gt;             duration;
    typedef chrono::time_point&lt;<i>unspecified, duration</i>&gt; time_point;
    static const bool is_monotonic =                  &lt;<i>unspecified</i>&gt;;

    static time_point now();
};
</pre>

<h2><a name="Threads"></a>Threads</h2>

<p>
The current time-related threading API is adapted to this proposal.  An emphasis is put on ease of use, safety,
efficiency, and durability with respect to advancing technology over time.
</p>

<p>
Summary of changes:
</p>

<ul>
<li>The parameters of the time-related functions have been modified to match the time API in this proposal.</li>
<li><code>sleep(rel_time)</code> has been renamed to <code>sleep_for(rel_time)</code>.</li>
<li><code>sleep(abs_time)</code> has been renamed to <code>sleep_until(abs_time)</code>.</li>
<li><code>timed_lock(rel_time)</code> has been renamed to <code>try_lock_for(rel_time)</code>.</li>
<li><code>timed_lock(abs_time)</code> has been renamed to <code>try_lock_until(abs_time)</code>.</li>
<li><code>timed_wait(rel_time)</code> has been renamed to <code>wait_for(rel_time)</code></li>
<li><code>timed_wait(abs_time)</code> has been renamed to <code>wait_until(abs_time)</code>.</li>
<li>The remark constraining the <code>unique_lock</code> constructor taking a <code>Duration</code> has been removed
(it is no longer needed).</li>
<li>A preference for the use of a monotonic clock has been stated for the <code>*_for</code> functions.</li>
</ul>

<h3><a name="Threads_wording"></a>Threads Proposed Wording</h3>

<p>
Modify 30.2 [thread.threads]:
</p>

<blockquote>
<pre>
<ins>template &lt;class Clock, class Duration&gt;</ins>
  void sleep<ins>_until</ins>(const <del>system_time</del> <ins>chrono::time_point&lt;Clock, Duration&gt;</ins>&amp; abs_time);
template &lt;class <del>Duration</del> <ins>Rep, class Period</ins>&gt; 
  void sleep<ins>_for</ins>(const <del>Duration</del> <ins>chrono::duration&lt;Rep, Period&gt;</ins>&amp; rel_time);
</pre>
</blockquote>

<p>
Modify 30.2.2 [thread.thread.this]:
</p>

<blockquote>
<pre>
<ins>template &lt;class Clock, class Duration&gt;</ins>
  void sleep<ins>_until</ins>(const <del>system_time</del> <ins>chrono::time_point&lt;Clock, Duration&gt;</ins>&amp; abs_time);
template &lt;class <del>Duration</del> <ins>Rep, class Period</ins>&gt; 
  void sleep<ins>_for</ins>(const <del>Duration</del> <ins>chrono::duration&lt;Rep, Period&gt;</ins>&amp; rel_time);
...
<ins>template &lt;class Clock, class Duration&gt;</ins>
  void this_thread::sleep<ins>_until</ins>(const <del>system_time</del> <ins>chrono::time_point&lt;Clock, Duration&gt;</ins>&amp; abs_time);
...
template &lt;class <del>Duration</del> <ins>Rep, class Period</ins>&gt; 
  void sleep<ins>_for</ins>(const <del>Duration</del> <ins>chrono::duration&lt;Rep, Period&gt;</ins>&amp; rel_time);
</pre>
<blockquote>
<p>...</p>
<p>
<ins>
[<i>Note:</i> Implementations should use a monotonic clock for measuring <code>rel_time</code> if available.
<i>-- end note</i>]</ins>
</p>
</blockquote>
</blockquote>

<p>
Modify 30.3.2 [thread.timedmutex.requirements]:
</p>

<blockquote>
<p>
A <code>TimedMutex</code> type shall meet the requirements for a
<code>Mutex</code> type. In addition, it shall meet the requirements set
out in this clause 30.3.2, where <code>rel_time</code> denotes <del>a value
of a type <code>RelTime</code> that meets the <code>Duration</code></del>
<ins>an instantiation of <code>duration</code></ins>
(??) <del>requirements</del> and <code>abs_time</code> denotes <del>a value of type
<code>std::system_time</code></del>
<ins>an instantiation of <code>time_point</code></ins>.
</p>

<p>
The expression <code>m.<del>timed_lock</del><ins>try_lock_for</ins>(rel_time)</code> shall be well-formed and have the following semantics:
</p>

<blockquote>
<p>
<i>Precondition:</i> If the <del>resolution</del> <ins>tick
<code>period</code></ins> of <code><del>RelTime</del>
<ins>rel_time</ins></code> is <del>finer than</del> <ins>not exactly convertible to</ins> the
native <del>resolution</del> <ins>tick <code>period</code></ins>, the
<del>time</del> <ins><code>duration</code></ins> shall be rounded up to
the nearest native <del>resolution</del> <ins>tick
<code>period</code></ins>.
</p>

<p>
<i>Effects:</i> The function attempts to obtain ownership of the mutex
within the time specified by <code>rel_time</code>. If the time specified
by <code>rel_time</code> is less than or equal to 0, the function
attempts to obtain ownership without blocking (as if by calling
<code>try_lock()</code>). The function shall return within the time
specified by <code>rel_time</code> only if it has obtained ownership of
the mutex object.
[<i>Note:</i> As with <code>try_lock()</code>, 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.
<ins>Implementations should use a monotonic clock for measuring <code>rel_time</code> if available.</ins>
<i>-- end note</i>]
</p>

<p>
<i>Return type:</i> <code>bool</code>
</p>

<p>
<i>Returns:</i> <code>true</code> if ownership was obtained, otherwise <code>false</code>.
</p>

<p>
<i>Synchronization:</i> If <code><del>timed_lock</del><ins>try_lock_for</ins>()</code> returns <code>true</code>,
prior <code>unlock()</code> operations on the same object synchronize 
with (1.10) this operation.
</p>

<p>
<i>Throws:</i> Nothing.
</p>
</blockquote>

<p>
The expression <code>m.<del>timed_lock</del><ins>try_lock_until</ins>(abs_time)</code> shall be well-formed and have
the following semantics:
</p>

<blockquote>
<p>
<i>Effects:</i> The function attempts to obtain ownership of the mutex
by the time specified by <code>abs_time</code>. If <code>abs_time</code> has already passed, the
function attempts to obtain ownership without blocking (as if by calling
<code>try_lock()</code>). The function shall return before the time
specified by <code>abs_time</code> only if it has obtained ownership of the mutex
object. [ <i>Note:</i> As with <code>try_lock()</code>, 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. <i>-- end
note</i>]
</p>

<p>
<i>Return type:</i> <code>bool</code>
</p>

<p>
<i>Returns:</i> <code>true</code> if ownership was obtained, otherwise <code>false</code>.
</p>

<p>
<i>Synchronization:</i> If <code><del>timed_lock</del><ins>try_lock_until</ins>()</code> returns
<code>true</code>, prior <code>unlock()</code> operations on the same
object synchronize with (1.10) this operation.
</p>

<p>
<i>Throws:</i> Nothing.
</p>

</blockquote>
</blockquote>

<p>
Modify 30.3.2.1 [thread.timedmutex.class]:
</p>

<blockquote><pre>
namespace std { 
  class timed_mutex { 
  public: 
    timed_mutex(); 
    ~timed_mutex(); 

    timed_mutex(const timed_mutex&amp;) = delete; 
    timed_mutex&amp; operator=(const timed_mutex&amp;) = delete; 

    void lock(); 
    bool try_lock(); 
    template &lt;class <del>Duration</del> <ins>Rep, class Period</ins>&gt; 
      bool <del>timed_lock</del><ins>try_lock_for</ins>(const <del>Duration</del> <ins>chrono::duration&lt;Rep, Period&gt;</ins>&amp; rel_time); 
    <ins>template &lt;class Clock, class Duration&gt;</ins>
      bool <del>timed_lock</del><ins>try_lock_until</ins>(const <del>system_time</del> <ins>chrono::time_point&lt;Clock, Duration&gt;</ins>&amp; abs_time); 
    void unlock(); 

    typedef implementation-defined native_handle_type; // See 30.1.3 
    native_handle_type native_handle();                // See 30.1.3 
  }; 
}
</pre>

<p>
The class <code>timed_mutex</code> provides a non-recursive mutex with
exclusive ownership semantics. If one thread owns a
<code>timed_mutex</code> object, attempts by another thread to acquire
ownership of that object will fail (for <code>try_lock()</code>) or
block (for <code>lock()</code><ins>, <code>try_lock_for()</code></ins> and
<code><del>timed_lock</del> <ins>try_lock_until</ins>()</code>) until the
owning thread has released ownership with a call to
<code>unlock()</code> or the call to <code><del>timed_lock</del> <ins>try_lock_for</ins>()</code>
<ins>or <code>try_lock_until()</code></ins> times out
(having failed to obtain ownership).
</p>

<p>
The class <code>timed_mutex</code> shall satisfy all of the
<code>TimedMutex</code> requirements (30.3.2). It shall be a
standard-layout class (9).
</p>

<p>
The behavior of a program is undefined if:
</p>

<ul>
<li>it destroys a <code>timed_mutex</code> object owned by any thread,</li>

<li>a thread that owns a <code>timed_mutex</code> object calls
<code>lock()</code>, <code>try_lock()</code><ins>,
<code>try_lock_for()</code> or <code>try_lock_until()</code></ins>
<del>or either overload of
<code>timed_lock()</code></del> on that object, or</li>

<li>a thread terminates while owning a <code>timed_mutex</code> object.</li>
</ul>

</blockquote>

<p>
Modify 30.3.2.2 [thread.timedmutex.recursive]:
</p>

<blockquote><pre>
namespace std { 
  class recursive_timed_mutex { 
  public: 
    recursive_timed_mutex(); 
    ~recursive_timed_mutex(); 

    recursive_timed_mutex(const recursive_timed_mutex&amp;) = delete; 
    recursive_timed_mutex&amp; operator=(const recursive_timed_mutex&amp;) = delete; 

    void lock(); 
    bool try_lock(); 
    template &lt;class <del>Duration</del> <ins>Rep, class Period</ins>&gt; 
      bool <del>timed_lock</del><ins>try_lock_for</ins>(const <del>Duration</del> <ins>chrono::duration&lt;Rep, Period&gt;</ins>&amp; rel_time); 
    <ins>template &lt;class Clock, class Duration&gt;</ins>
      bool <del>timed_lock</del><ins>try_lock_until</ins>(const <del>system_time</del> <ins>chrono::time_point&lt;Clock, Duration&gt;</ins>&amp; abs_time); 
    void unlock(); 

    typedef implementation-defined native_handle_type; // See 30.1.3 
    native_handle_type native_handle();                // See 30.1.3 
  }; 
}
</pre>

<p>
The class <code>recursive_timed_mutex</code> provides a non-recursive mutex with
exclusive ownership semantics. If one thread owns a
<code>recursive_timed_mutex</code> object, attempts by another thread to acquire
ownership of that object will fail (for <code>try_lock()</code>) or
block (for <code>lock()</code><ins>, <code>try_lock_for()</code></ins> and
<code><del>timed_lock</del> <ins>try_lock_until</ins>()</code>) until the
owning thread has released ownership with a call to
<code>unlock()</code> or the call to <code><del>timed_lock</del> <ins>try_lock_for</ins>()</code>
<ins>or <code>try_lock_until()</code></ins> times out
(having failed to obtain ownership).
</p>

<p>
The class <code>recursive_timed_mutex</code> shall satisfy all of the
<code>TimedMutex</code> requirements (30.3.2). It shall be a
standard-layout class (9).
</p>

<p>
A thread that owns a <code>recursive_timed_mutex</code> object may
acquire additional levels of ownership by calling <code>lock()</code>,
<code>try_lock()</code><ins>, try_lock_for()</ins> or <del>timed_lock()</del>
<ins>try_lock_until()</ins> on that object. It is unspecified how many
levels of ownership may be acquired by a single thread. If a thread has
already acquired the maximum level of ownership for a
<code>recursive_timed_mutex</code> object, additional calls to
<code>try_lock()</code><ins>, try_lock_for()</ins> or <del>timed_lock()</del>
<ins>try_lock_until()</ins> shall fail, and additional calls to
<code>lock()</code> shall throw an exception of type std::system_error.
A thread shall call <code>unlock()</code> once for each level of ownership acquired
by calls to <code>lock()</code>, <code>try_lock()</code><ins>, try_lock_for()</ins> and <del>timed_lock()</del>
<ins>try_lock_until()</ins>. Only when
all levels of ownership have been released may ownership of the object
be acquired by another thread.
</p>

<p>
The behavior of a program is undefined if:
</p>

<ul>
<li>it destroys a <code>recursive_timed_mutex</code> object owned by any thread, or</li>

<li>a thread terminates while owning a <code>recursive_timed_mutex</code> object.</li>
</ul>

</blockquote>

<p>
Modify 30.3.3.2 [thread.lock.unique]:
</p>

<blockquote>
<pre>
namespace std { 
template &lt;class Mutex&gt; 
class unique_lock { 
public: 
    typedef Mutex mutex_type; 

    // 30.3.3.2.1 construct/copy/destroy 
    unique_lock(); 
    explicit unique_lock(mutex_type&amp; m); 
    unique_lock(mutex_type&amp; m, defer_lock_t);
    unique_lock(mutex_type&amp; m, try_to_lock_t); 
    unique_lock(mutex_type&amp; m, adopt_lock_t);
    <ins>template &lt;class Clock, class Duration&gt;</ins>
      unique_lock(mutex_type&amp; m, const <del>system_time</del> <ins>chrono::time_point&lt;Clock, Duration&gt;</ins>&amp; abs_time); 
    template &lt;class <del>Duration</del> <ins>Rep, class Period</ins>&gt; 
      unique_lock(mutex_type&amp; m, const <del>Duration</del> <ins>chrono::duration&lt;Rep, Period&gt;</ins>&amp; rel_time); 
    ~unique_lock(); 

    unique_lock(unique_lock const&amp;) = delete; 
    unique_lock&amp; operator=(unique_lock const&amp;) = delete; 

    unique_lock(unique_lock&amp;&amp; u); 
    unique_lock&amp; operator=(unique_lock&amp;&amp; u); 

    // 30.3.3.2.2 locking 
    void lock(); 
    bool try_lock(); 
    template &lt;class <del>Duration</del> <ins>Rep, class Period</ins>&gt; 
      bool <del>timed</del><ins>try</ins>_lock<ins>_for</ins>(const <del>Duration</del> <ins>chrono::duration&lt;Rep, Period&gt;</ins>&amp; rel_time); 
    <ins>template &lt;class Clock, class Duration&gt;</ins>
      bool <del>timed</del><ins>try</ins>_lock<ins>_until</ins>(const <del>system_time</del> <ins>chrono::time_point&lt;Clock, Duration&gt;</ins>&amp; abs_time); 
    void unlock(); 

    // 30.3.3.2.3 modifiers 
    void swap(unique_lock&amp;&amp; u); 
    mutex_type* release(); 

    // 30.3.3.2.4 observers 
    bool owns_lock() const; 
    explicit operator bool () const; 
    mutex_type* mutex() const; 

private: 
    // exposition only: 
    mutex_type* pm; 
    bool owns; 
};

...
</pre>

</blockquote>

<p>
Modify 30.3.3.2.1 [thread.lock.unique.cons]:
</p>

<blockquote>
<pre>
<ins>template &lt;class Clock, class Duration&gt;</ins>
  unique_lock(mutex_type&amp; m, const <del>system_time</del> <ins>chrono::time_point&lt;Clock, Duration&gt;</ins>&amp; abs_time);
</pre>

<blockquote>
<p>
<i>Precondition:</i> If <code>mutex_type</code> is not a recursive mutex the calling thread does not own the mutex.
</p>
<p>
<i>Effects:</i> Constructs an object of type <code>unique_lock</code> and calls
<code>m.<del>timed</del><ins>try</ins>_lock<ins>_until</ins>(abs_time)</code>.
</p>
<p>
<i>Postconditions:</i> <code>pm == &amp;m</code> and <code>owns ==
res</code>, where <code>res</code> is the value returned by the call to
<code><del>timed</del><ins>try</ins>_lock<ins>_until</ins>(abs_time)</code>.
</p>
<p>
<i>Throws:</i> Nothing.
</p>
</blockquote>

<pre>
template &lt;class <del>Duration</del> <ins>Rep, class Period</ins>&gt; 
  unique_lock(mutex_type&amp; m, const <del>Duration</del> <ins>chrono::duration&lt;Rep, Period&gt;</ins>&amp; rel_time); 
</pre>

<blockquote>
<p>
<del><i>Remark:</i> The implementation shall ensure that only <code>Duration</code> types (") will bind to this constructor.</del>
</p>
<p>
<i>Precondition:</i> If <code>mutex_type</code> is not a recursive mutex the calling thread does not own the mutex.
</p>
<p>
<i>Effects:</i> Constructs an object of type <code>unique_lock</code> and calls
<code>m.<del>timed</del><ins>try</ins>_lock<ins>_for</ins>(rel_time)</code>.
</p>
<p>
<i>Postconditions:</i> <code>pm == &amp;m</code> and <code>owns ==
res</code>, where <code>res</code> is the value returned by the call to
<code>m.<del>timed</del><ins>try</ins>_lock<ins>_for</ins>(rel_time)</code>.
</p>
<p>
<i>Throws:</i> Nothing.
</p>
</blockquote>

</blockquote>

<p>
Modify 30.3.3.2.2 [thread.lock.unique.locking]:
</p>

<blockquote>
<pre>
<ins>template &lt;class Clock, class Duration&gt;</ins>
  bool <del>timed</del><ins>try</ins>_lock<ins>_until</ins>(const <del>system_time</del> <ins>chrono::time_point&lt;Clock, Duration&gt;</ins>&amp; abs_time);
</pre>

<blockquote>
<p>
<i>Effects:</i> <code>pm-&gt;<del>timed</del><ins>try</ins>_lock<ins>_until</ins>(abs_time)</code>
</p>
<p>
<i>Returns:</i> The value returned by the call to <code><del>timed</del><ins>try</ins>_lock<ins>_until</ins>(abs_time)</code>.
</p>
<p>
<i>Postcondition:</i> <code>owns == res</code>, where <code>res</code> is the value returned by the call to
<code><del>timed</del><ins>try</ins>_lock<ins>_until</ins>(abs_time)</code>.
</p>
<p>
<i>Throws:</i> <code>lock_error</code> if on entry <code>owns</code> is <code>true</code> or <code>pm</code> is null.
</p>
</blockquote>

<pre>
template &lt;class <del>Duration</del> <ins>Rep, class Period</ins>&gt; 
  bool <del>timed</del><ins>try</ins>_lock<ins>_for</ins>(const <del>Duration</del> <ins>chrono::duration&lt;Rep, Period&gt;</ins>&amp; rel_time);
</pre>

<blockquote>
<p>
<i>Effects:</i> <code>pm-&gt;<del>timed</del><ins>try</ins>_lock<ins>_for</ins>(rel_time)</code>
</p>
<p>
<i>Returns:</i> The value returned by the call to <code><del>timed</del><ins>try</ins>_lock<ins>_for</ins>(rel_time)</code>.
</p>
<p>
<i>Postcondition:</i> <code>owns == res</code>, where <code>res</code> is the value returned by the call to
<code><del>timed</del><ins>try</ins>_lock<ins>_for</ins>(rel_time)</code>.
</p>
<p>
<i>Throws:</i> <code>lock_error</code> if on entry <code>owns</code> is true or <code>pm</code> is null.
</p>
</blockquote>
</blockquote>

<p>
Modify 30.4 [thread.condition]:
</p>

<blockquote>
<p>
...
</p>
<p>
Condition variables permit concurrent invocation of the <code>wait</code>, <code><del>timed_</del>wait<ins>_for</ins></code>,
<code><del>timed_</del>wait<ins>_until</ins></code>, <code>notify_one</code> and <code>notify_all</code> member functions.
</p>
<p>
...
</p>
<p>
The implementation shall behave as if <code>notify_one</code>,
<code>notify_all</code>, and each part of the <code>wait</code><ins>,
wait_for</ins> and <code><del>timed_</del>wait<ins>_until</ins></code>
executions are executed in some unspecified total order.
</p>
<p>
...
</p>
</blockquote>

<p>
Modify 30.4.1 [thread.condition.condvar]:
</p>

<blockquote>
<pre>
namespace std { 
class condition_variable { 
public: 

    condition_variable(); 
    ~condition_variable(); 

    condition_variable(const condition_variable&amp;) = delete; 
    condition_variable&amp; operator=(const condition_variable&amp;) = delete; 

    void notify_one(); 
    void notify_all(); 
    void wait(unique_lock&lt;mutex&gt;&amp; lock); 
    template &lt;class Predicate&gt; 
      void wait(unique_lock&lt;mutex&gt;&amp; lock, Predicate pred); 
<del>    template &lt;class Duration&gt; 
      bool timed_wait(unique_lock&lt;mutex&gt;&amp; lock, const Duration&amp; rel_time); 
    bool timed_wait(unique_lock&lt;mutex&gt;&amp; lock, const system_time&amp; abs_time); 
    template &lt;class Predicate&gt; 
      bool timed_wait(unique_lock&lt;mutex&gt;&amp; lock, const system_time&amp; abs_time, 
                      Predicate pred); 
    template &lt;class Duration, class Predicate&gt; 
      bool timed_wait(unique_lock&lt;mutex&gt;&amp; lock, const Duration&amp; rel_time, Predicate pred);</del>

<ins>    template &lt;class Clock, class Duration&gt;
        bool wait_until(unique_lock&lt;mutex&gt;&amp; lock,
                        const chrono::time_point&lt;Clock, Duration&gt;&amp; abs_time);
    template &lt;class Clock, class Duration, class Predicate&gt;
        bool wait_until(unique_lock&lt;mutex&gt;&amp; lock,
                        const chrono::time_point&lt;Clock, Duration&gt;&amp; abs_time,
                        Predicate pred);

    template &lt;class Rep, class Period&gt;
        bool wait_for(unique_lock&lt;mutex&gt;&amp; lock, const chrono::duration&lt;Rep, Period&gt;&amp; rel_time);
    template &lt;class Rep, class Period, class Predicate&gt;
        bool wait_for(unique_lock&lt;mutex&gt;&amp; lock,  const chrono::duration&lt;Rep, Period&gt;&amp; rel_time,
                      Predicate pred);</ins>

    typedef implementation-defined native_handle_type; // See 30.1.3 
    native_handle_type native_handle(); // See 30.1.3 
}; 
}
</pre>

<p>...</p>

<pre>
<ins>template &lt;class Clock, class Duration&gt;</ins>
  bool <del>timed_</del>wait<ins>_until</ins>(unique_lock&lt;mutex&gt;&amp; lock, const <del>system_time</del> <ins>chrono::time_point&lt;Clock, Duration&gt;</ins>&amp; abs_time);
</pre>

<blockquote>
<p>
<i>Precondition:</i> <code>lock</code> is locked by the calling thread, and either
</p>
<ul>
<li>
no other thread is waiting on this <code>condition_variable</code> object or
</li>
<li>
<code>lock.mutex()</code> returns the same value for each of the <code>lock</code> arguments supplied by all concurrently waiting 
threads (via <code>wait</code><ins>, <code>wait_for</code></ins> or <code><del>timed_</del>wait<ins>_until</ins></code>).
</li>
</ul>
<p>
<i>Effects:</i>
</p>
<ul>
<li>
Atomically calls <code>lock.unlock()</code> and blocks on <code>*this</code>.
</li>
<li>
When unblocked, calls <code>lock.lock()</code> (possibly blocking on the <code>lock</code>) and returns.
</li>
<li>
The function will unblock when signaled by a call to <code>notify_one()</code>, a call to <code>notify_all()</code>,
by the current time exceeding <code>abs_time</code>, or spuriously.
</li>
<li>
If the function exits via an exception, <code>lock.unlock()</code> shall be called prior to exiting the function scope.
</li>
</ul>
<p>
<i>Postcondition:</i> <code>lock</code> is locked by the calling thread.
</p>
<p>
<i>Returns:</i> <ins><code>Clock::now() &lt; abs_time</code></ins> <del><code>false</code> if the call is returning because the time specified by <code>abs_time</code>
was reached, otherwise <code>true</code></del>.
</p>
<p>
<i>Throws:</i> <code>std::system_error</code> when the returned value, effects, or postcondition cannot be achieved.
</p>
</blockquote>

<pre>
template &lt;<ins>class Clock, class Duration,</ins> class Predicate&gt; 
  bool <del>timed_</del>wait<ins>_until</ins>(unique_lock&lt;mutex&gt;&amp; lock,
                        const <del>system_time</del> <ins>chrono::time_point&lt;Clock, Duration&gt;</ins>&amp; abs_time, 
                        Predicate pred);
</pre>

<blockquote>
<p>
<i>Effects:</i>
</p>
<blockquote><pre>
while (!pred()) 
    if (!<del>timed_</del>wait<ins>_until</ins>(lock, abs_time)) 
        return pred(); 
return true;
</pre></blockquote>

<p>...</p>

</blockquote>

<pre>
template &lt;class <del>Duration</del> <ins>Rep, class Period</ins>&gt; 
  bool <del>timed_</del>wait<ins>_for</ins>(unique_lock&lt;mutex&gt;&amp; lock, const <del>Duration</del> <ins>chrono::duration&lt;Rep, Period&gt;</ins>&amp; rel_time);
</pre>

<blockquote>
<p>
<ins><i>Effects:</i> As if </ins><code><del>timed_</del>wait<ins>_until</ins>(lock, <del>std::get_system_time()</del> <ins>chrono::monotonic_clock::now()</ins> + rel_time)</code>
</p>
<p>
<i>Returns:</i> <code>false</code> if the call is returning because the time duration specified by <code>rel_time</code>
has elapsed, otherwise <code>true</code>.
</p>

<p>
<ins><i>Note:</i> A monotonic clock is preferred but not required for measuring <code>rel_time</code> in this
function.</ins>
</p>
</blockquote>

<pre>
template &lt;class <del>Duration</del> <ins>Rep, class Period</ins>, class Predicate&gt; 
  bool <del>timed_</del>wait<ins>_for</ins>(unique_lock&lt;mutex&gt;&amp; lock,
                      const <del>Duration</del> <ins>chrono::duration&lt;Rep, Period&gt;</ins>&amp; rel_time,
                      Predicate pred);
</pre>

<blockquote>
<p>
<i>Effects:</i>
</p>
<blockquote><pre>
<del>timed_</del>wait<ins>_until</ins>(lock, <del>std::get_system_time()</del> <ins>chrono::monotonic_clock::now()</ins> + rel_time, std::move(pred))
</pre></blockquote>

<p>
[<i>Note:</i> There is no blocking if <code>pred()</code> is initially <code>true</code>,
even if the timeout has already expired. 
<ins>A monotonic clock is preferred but not required for measuring <code>rel_time</code> in this function.</ins>
<i>-- end note</i>]
</p>

<p>...</p>

</blockquote>

</blockquote>

<p>
Modify 30.4.2 [thread.condition.condvarany]:
</p>

<blockquote>
<pre>
namespace std { 
class condition_variable_any { 
public: 
    condition_variable_any(); 
    ~condition_variable_any(); 

    condition_variable_any(const condition_variable_any&amp;) = delete; 
    condition_variable_any&amp; operator=(const condition_variable_any&amp;) = delete; 

    void notify_one(); 
    void notify_all(); 

    template &lt;class Lock&gt; 
      void wait(Lock&amp; lock); 
    template &lt;class Lock, class Predicate&gt; 
      void wait(Lock&amp; lock, Predicate pred); 

    <del>template &lt;class Lock&gt; 
      bool timed_wait(Lock&amp; lock, const system_time&amp; abs_time); 
    template &lt;class Lock, class Duration&gt; 
      bool timed_wait(Lock&amp; lock, const Duration&amp; rel_time); 
    template &lt;class Lock, class Predicate&gt; 
      bool timed_wait(Lock&amp; lock, const system_time&amp; abs_time, Predicate pred); 
    template &lt;class Lock, class Duration, class Predicate&gt; 
      bool timed_wait(Lock&amp; lock, const Duration&amp; rel_time, Predicate pred);</del>

    <ins>template &lt;class Lock, class Clock, class Duration&gt;
        bool wait_until(Lock&amp; lock, const chrono::time_point&lt;Clock, Duration&gt;&amp; abs_time);
    template &lt;class Lock, class Clock, class Duration, class Predicate&gt;
        bool wait_until(Lock&amp; lock, const chrono::time_point&lt;Clock, Duration&gt;&amp; abs_time,
                        Predicate pred);

    template &lt;class Lock, class Rep, class Period&gt;
        bool wait_for(Lock&amp; lock, const chrono::duration&lt;Rep, Period&gt;&amp; rel_time);
    template &lt;class Lock, class Rep, class Period, class Predicate&gt;
        bool wait_for(Lock&amp; lock, const chrono::duration&lt;Rep, Period&gt;&amp; rel_time, Predicate pred);</ins>

    typedef implementation-defined native_handle_type; // See 30.1.3 
    native_handle_type native_handle(); // See 30.1.3 
}; 
}
</pre>

<p>...</p>

<pre>
template &lt;class Lock<ins>, class Clock, class Duration&gt;</ins>
  bool <del>timed_</del>wait<ins>_until</ins>(Lock&amp; lock, const <del>system_time</del> <ins>chrono::time_point&lt;Clock, Duration&gt;</ins>&amp; abs_time);
</pre>

<blockquote>
<p>
<i>Effects:</i>
</p>
<ul>
<li>
Atomically calls <code>lock.unlock()</code> and blocks on <code>*this</code>.
</li>
<li>
When unblocked, calls <code>lock.lock()</code> (possibly blocking on the <code>lock</code>) and returns.
</li>
<li>
The function will unblock when signaled by a call to <code>notify_one()</code>, a call to <code>notify_all()</code>,
by the current time exceeding <code>abs_time</code>, or spuriously.
</li>
<li>
If the function exits via an exception, <code>lock.unlock()</code> shall be called prior to exiting the function scope.
</li>
</ul>
<p>
<i>Postcondition:</i> <code>lock</code> is locked by the calling thread.
</p>
<p>
<i>Returns:</i> <ins><code>Clock::now() &lt; abs_time</code></ins> <del><code>false</code> if the call is returning
because the time specified by <code>abs_time</code> was reached, otherwise <code>true</code></del>.
</p>
<p>
<i>Throws:</i> <code>std::system_error</code> when the returned value, effects, or postcondition cannot be achieved.
</p>
</blockquote>

<pre>
template &lt;class Lock<ins>, class Clock, class Duration,</ins> class Predicate&gt; 
  bool <del>timed_</del>wait<ins>_until</ins>(Lock&amp; lock,
                        const <del>system_time</del> <ins>chrono::time_point&lt;Clock, Duration&gt;</ins>&amp; abs_time, 
                        Predicate pred);
</pre>

<blockquote>
<p>
<i>Effects:</i>
</p>
<blockquote><pre>
while (!pred()) 
    if (!<del>timed_</del>wait<ins>_until</ins>(lock, abs_time)) 
        return pred(); 
return true;
</pre></blockquote>

<p>...</p>

</blockquote>

<pre>
template &lt;class Lock, class <del>Duration</del> <ins>Rep, class Period</ins>&gt; 
  bool <del>timed_</del>wait<ins>_for</ins>(Lock&amp; lock, const <del>Duration</del> <ins>chrono::duration&lt;Rep, Period&gt;</ins>&amp; rel_time);
</pre>

<blockquote>
<p>
<i>Effects:</i> <ins>As if </ins><code><del>timed_</del>wait<ins>_until</ins>(lock, <del>std::get_system_time()</del> <ins>chrono::monotonic_clock::now()</ins> + rel_time)</code>
</p>
<p>
<i>Returns:</i> <code>false</code> if the call is returning because the time duration specified by <code>rel_time</code>
has elapsed, otherwise <code>true</code>.
</p>

<p>
<ins><i>Note:</i> A monotonic clock is preferred but not required for measuring <code>rel_time</code> in this
function.</ins>
</p>
</blockquote>

<pre>
template &lt;class Lock, class <del>Duration</del> <ins>Rep, class Period</ins>, class Predicate&gt; 
  bool <del>timed_</del>wait<ins>_for</ins>(Lock&amp; lock,
                      const <del>Duration</del> <ins>chrono::duration&lt;Rep, Period&gt;</ins>&amp; rel_time,
                      Predicate pred);
</pre>

<blockquote>
<p>
<i>Effects:</i>
</p>
<blockquote><pre>
<del>timed_</del>wait<ins>_until</ins>(lock, <del>std::get_system_time()</del> <ins>chrono::monotonic_clock::now()</ins> + rel_time, std::move(pred))
</pre></blockquote>

<p>
[<i>Note:</i> There is no blocking if <code>pred()</code> is initially <code>true</code>,
even if the timeout has already expired. 
<ins>A monotonic clock is preferred but not required for measuring <code>rel_time</code> in this function.</ins>
<i>-- end note</i>]
</p>

<p>...</p>

</blockquote>

</blockquote>

<h2><a name="Acknowledgements"></a>Acknowledgements</h2>

<p>
The help of many people in preparing the technical background of this
paper is much appreciated.  Special thanks to Andrei Alexandrescu,
Lawrence Crowl, Beman Dawes, Peter Dimov, Terry Golubiewski, Daniel
Kr&uuml;gler and Anthony Williams.
</p>

</body>
</html>
