Using ytime for Times in the Thread Support Library

These are the changes to N2521, Working Draft, Standard for Programming Language C++, to replace the date and time material in Clause 31 with ytime.

Additions to the previous version of this draft paper are marked like this. Additions and changes include:

• added words to more clearly describe how the members sec and nsec interact to define a time
• added changes to the Effects clauses of various timed_wait and timed_wait_until member functions to correctly specify their behavior using the new names
• changed xtime to ytime throughout (not marked).

Changes to the working draft:

1. In 30.1.4, [thread.req.timing], replace paragraphs 1 and 2 with the following:

   The class ytime designates a time duration or a point in time. The headers <thread> and <condition> shall provide idempotent definitions of this class and of the enumeration TIME_UTC.

2. In 30.2, [thread.threads], change the synopsis for the header <thread> to read as follows:

   // times [cross-reference goes here]
   class ytime;
   enum { TIME_UTC = <integer constant expression> };
   int ytime_get(ytime& xt, int time_base);
   void sleep sleep_until (const system_time ytime& abs_time);
   template <class Duration>
       void sleep(const Duration ytime& rel_time);

3. Before 30.2.1, [thread.thread.class], add a new subclause, Times, to read as follows:

   enum { TIME_UTC = <integer constant expression> };

   The compile-time constant is a non-zero value that designates the system’s approximation of Coordinated Universal Time (UTC) as the time base for the values set by ytime_get.

   struct ytime {
       time_t sec;
       unsigned long nsec;
       };

   The struct ytime contains members that describe times with nanosecond resolution. An object of type ytime can represent a time duration or it can represent an absolute time. The member sec holds the number of seconds and the member nsec holds the number of nanoseconds. The time represented by such an object is sec * 1,000,000,000 + nsec nanoseconds past the implementation-specific epoch.

   The type time_t is defined in <ctime>.

   int ytime_get(ytime& xt, int time_base);

   The function sets the ytime object referred to by xt to hold the current time based on the non-zero time base selector time_base. If successful it returns time_base; otherwise it returns 0. [Note: The value of time_base will typically be TIME_UTC. -- end note]

4. In 30.2.2, [thread.thread.this], change the synopsis for namespace this_thread to read as follows:

   void sleep sleep_until (const system_time ytime& abs_time);
   template <class Duration>
   void sleep(const Duration ytime& rel_time);

5. In 30.2.2, [thread.thread.this], change the declaration of the first overload of the sleep function to read as follows:

   void this_thread::sleep sleep_until (const system_time ytime& abs_time);

6. In 30.2.2, [thread.thread.this], change the declaration of the second overload of the sleep function to read as follows:

   template <class Duration>
   void this_thread::sleep(const Duration ytime& rel_time);

7. In 30.4, [thread.condition], add the following to the synopsis for the header <condition_variable>

   // times [cross-reference goes here]
   class ytime;
   enum { TIME_UTC = <integer constant expression> };
   int ytime_get(ytime& xt, int time_base);
   

8. In 30.4.1, [thread.condition.condvar], change the synopsis for the class condition_variable to read as follows:

   template <class Duration>
   bool timed_wait(unique_lock<mutex>& lock, const Duration ytime & rel_time);
   bool timed_wait timed_wait_until (unique_lock<mutex>& lock,
       const system_time ytime& abs_time);
   template <class Predicate>
       bool timed_wait timed_wait_until (unique_lock<mutex>& lock,
           const system_time ytime& abs_time, Predicate pred);
   template <class Duration, class Predicate>
       bool timed_wait(unique_lock<mutex>& lock, const Duration ytime & rel_time,
           Predicate pred);
   

9. In 30.4.1, [thread.condition.condvar], change the declaration of the first overload of the timed_wait function to read as follows:

   bool timed_wait timed_wait_until (unique_lock<mutex>& lock, const system_time ytime& abs_time);

10. In 30.4.1, [thread.condition.condvar], change the declaration of the second overload of the timed_wait function to read as follows:

    template <class Duration>
    bool timed_wait(unique_lock<mutex>& lock, const Duration ytime& rel_time);

11. In 30.4.1, [thread.condition.condvar], change the Effects clause of the second overload of the timed_wait function to read as follows:

    ytime xt;
    ytime_get(xt, TIME_UTC);
    xt.sec += rel_time.sec;
    xt.nsec += rel_time.nsec;
    timed_wait_until(lock, xt);

12. In 30.4.1, [thread.condition.condvar], change the declaration of the third overload of the timed_wait function to read as follows:

    template <class Predicate>
        bool timed_wait timed_wait_until (unique_lock<mutex>& lock,
            const system_time ytime& abs_time, Predicate pred);

13. In 30.4.1, [thread.condition.condvar], change the Effects clause of the third overload of the timed_wait function to read as follows:

    while (!pred())
      if (!timed_wait timed_wait_until(lock, abs_time))
        return pred();
    return true;

14. In 30.4.1, [thread.condition.condvar], change the declaration of the fourth overload of the timed_wait function to read as follows:

    template <class Duration, class Predicate>
        bool timed_wait(unique_lock<mutex>& lock,
            const Duration ytime& rel_time, Predicate pred);

15. In 30.4.1, [thread.condition.condvar], change the Effects clause of the fourth overload of the timed_wait function to read as follows:

    ytime xt;
    ytime_get(xt, TIME_UTC);
    xt.sec += rel_time.sec;
    xt.nsec += rel_time.nsec;
    timed_wait_until(lock, xt, std::move(pred));

16. In 30.4.2, [thread.condition.condvarany], change the synopsis for the class condition_variable_any to read as follows:

    template <class Lock>
        bool timed_wait timed_wait_until (Lock& lock, const system_time ytime& abs_time);
    template <class Lock, class Duration>
        bool timed_wait(Lock& lock, const Duration ytime & rel_time);
    template <class Lock, class Predicate>
        bool timed_wait timed_wait_until (Lock& lock, const system_time ytime& abs_time, Predicate pred);
    template <class Lock, class Duration, class Predicate>
        bool timed_wait(Lock& lock, const Duration ytime & rel_time, Predicate pred);
    

17. In 30.4.2, [thread.condition.condvarany], change the declaration of the first overload of the timed_wait function to read as follows:

    template <class Lock>
        bool timed_wait timed_wait_until (Lock lock, const system_time ytime& abs_time);

18. In 30.4.2, [thread.condition.condvarany], change the declaration of the second overload of the timed_wait function to read as follows:

    template <class Lock, class Duration>
        bool timed_wait(Lock lock, const Duration ytime& rel_time);

19. In 30.4.2, [thread.condition.condvarany], change the Effects clause of the second overload of the timed_wait function to read as follows:

    ytime xt;
    ytime_get(xt, TIME_UTC);
    xt.sec += rel_time.sec;
    xt.nsec += rel_time.nsec;
    timed_wait_until(lock, xt);

20. In 30.4.2, [thread.condition.condvarany], change the declaration of the third overload of the timed_wait function to read as follows:

    template <class Lock, class Predicate>
        bool timed_wait timed_wait_until (Lock lock,
            const system_time ytime& abs_time, Predicate pred);

21. In 30.4.2, [thread.condition.condvarany], change the Effects clause of the third overload of the timed_wait function to read as follows:

    while (!pred())
      if (!timed_wait timed_wait_until(lock, abs_time))
        return pred();
    return true;

22. In 30.4.2, [thread.condition.condvarany], change the declaration of the fourth overload of the timed_wait function to read as follows:

    template <class Lock, class Duration, class Predicate>
        bool timed_wait(Lock lock,
            const Duration ytime& rel_time, Predicate pred);

23. In 30.4.2, [thread.condition.condvarany], change the Effects clause of the fourth overload of the timed_wait function to read as follows:

    ytime xt;
    ytime_get(xt, TIME_UTC);
    xt.sec += rel_time.sec;
    xt.nsec += rel_time.nsec;
    timed_wait_until(lock, xt, std::move(pred));

24. Remove clause 31.