OLD | NEW |
---|---|
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. | 1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 // Time represents an absolute point in coordinated universal time (UTC), | 5 // Time represents an absolute point in coordinated universal time (UTC), |
6 // internally represented as microseconds (s/1,000,000) since the Windows epoch | 6 // internally represented as microseconds (s/1,000,000) since the Windows epoch |
7 // (1601-01-01 00:00:00 UTC) (See http://crbug.com/14734). System-dependent | 7 // (1601-01-01 00:00:00 UTC). System-dependent clock interface routines are |
8 // clock interface routines are defined in time_PLATFORM.cc. | 8 // defined in time_PLATFORM.cc. Note that values for Time may skew and jump |
9 // around as the operating system makes adjustments to synchronize (e.g., with | |
10 // NTP servers). Thus, client code that uses the Time class must account for | |
11 // this. | |
9 // | 12 // |
10 // TimeDelta represents a duration of time, internally represented in | 13 // TimeDelta represents a duration of time, internally represented in |
11 // microseconds. | 14 // microseconds. |
12 // | 15 // |
13 // TimeTicks represents an abstract time that is most of the time incrementing | 16 // TimeTicks, ThreadTicks, and TraceTicks represent an abstract time that is |
14 // for use in measuring time durations. It is internally represented in | 17 // most of the time incrementing, for use in measuring time |
15 // microseconds. It can not be converted to a human-readable time, but is | 18 // durations. Internally, they are represented in microseconds. They can not be |
Lei Zhang
2015/05/28 22:54:08
nit: there's space on the previous line.
miu
2015/05/29 19:54:17
Done.
| |
16 // guaranteed not to decrease (if the user changes the computer clock, | 19 // converted to a human-readable time, but are guaranteed not to decrease |
17 // Time::Now() may actually decrease or jump). But note that TimeTicks may | 20 // (unlike the Time class). Note that TimeTicks may "stand still" (e.g., if the |
18 // "stand still", for example if the computer suspended. | 21 // computer is suspended), and ThreadTicks will "stand still" whenever the |
22 // thread has been de-scheduled by the operating system. | |
19 // | 23 // |
20 // These classes are represented as only a 64-bit value, so they can be | 24 // All time classes are copyable, assignable, and occupy 64-bits per |
21 // efficiently passed by value. | 25 // instance. Thus, they can be efficiently passed by-value (as opposed to |
26 // by-reference). | |
22 // | 27 // |
23 // Definitions of operator<< are provided to make these types work with | 28 // Definitions of operator<< are provided to make these types work with |
24 // DCHECK_EQ() and other log macros. For human-readable formatting, see | 29 // DCHECK_EQ() and other log macros. For human-readable formatting, see |
25 // "base/i18n/time_formatting.h". | 30 // "base/i18n/time_formatting.h". |
31 // | |
32 // So many choices! Which time class should you use? Examples: | |
33 // | |
34 // Time: Interpreting the wall-clock time provided by a remote | |
35 // system. Detecting whether cached resources have | |
36 // expired. Providing the user with a display of the current date | |
37 // and time. Determining the amount of time between events across | |
38 // re-boots of the machine. | |
39 // | |
40 // TimeTicks: Tracking the amount of time a task runs. Executing delayed | |
41 // tasks at the right time. Computing presentation timestamps. | |
42 // Synchronizing audio and video using TimeTicks as a common | |
43 // reference clock (lip-sync). Measuring network round-trip | |
44 // latency. | |
45 // | |
46 // ThreadTicks: Benchmarking how long the current thread has been doing actual | |
47 // work. | |
48 // | |
49 // TraceTicks: This is only meant to be used by the event tracing | |
50 // infrastructure, and by outside code modules in special | |
51 // circumstances. Please be sure to consult a | |
52 // base/trace_event/OWNER before committing any new code that | |
53 // uses this. | |
26 | 54 |
27 #ifndef BASE_TIME_TIME_H_ | 55 #ifndef BASE_TIME_TIME_H_ |
28 #define BASE_TIME_TIME_H_ | 56 #define BASE_TIME_TIME_H_ |
29 | 57 |
30 #include <time.h> | 58 #include <time.h> |
31 | 59 |
32 #include <iosfwd> | 60 #include <iosfwd> |
33 | 61 |
34 #include "base/base_export.h" | 62 #include "base/base_export.h" |
35 #include "base/basictypes.h" | 63 #include "base/basictypes.h" |
(...skipping 596 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
632 } | 660 } |
633 | 661 |
634 // For logging use only. | 662 // For logging use only. |
635 BASE_EXPORT std::ostream& operator<<(std::ostream& os, Time time); | 663 BASE_EXPORT std::ostream& operator<<(std::ostream& os, Time time); |
636 | 664 |
637 // TimeTicks ------------------------------------------------------------------ | 665 // TimeTicks ------------------------------------------------------------------ |
638 | 666 |
639 // Represents monotonically non-decreasing clock time. | 667 // Represents monotonically non-decreasing clock time. |
640 class BASE_EXPORT TimeTicks : public time_internal::TimeBase<TimeTicks> { | 668 class BASE_EXPORT TimeTicks : public time_internal::TimeBase<TimeTicks> { |
641 public: | 669 public: |
642 // We define this even without OS_CHROMEOS for seccomp sandbox testing. | |
643 #if defined(OS_LINUX) | |
644 // Force definition of the system trace clock; it is a chromeos-only api | |
645 // at the moment and surfacing it in the right place requires mucking | |
646 // with glibc et al. | |
647 static const clockid_t kClockSystemTrace = 11; | |
648 #endif | |
649 | |
650 TimeTicks() : TimeBase(0) { | 670 TimeTicks() : TimeBase(0) { |
651 } | 671 } |
652 | 672 |
653 // Platform-dependent tick count representing "right now." When | 673 // Platform-dependent tick count representing "right now." When |
654 // IsHighResolution() returns false, the resolution of the clock could be | 674 // IsHighResolution() returns false, the resolution of the clock could be |
655 // as coarse as ~15.6ms. Otherwise, the resolution should be no worse than one | 675 // as coarse as ~15.6ms. Otherwise, the resolution should be no worse than one |
656 // microsecond. | 676 // microsecond. |
657 static TimeTicks Now(); | 677 static TimeTicks Now(); |
658 | 678 |
659 // Returns true if the high resolution clock is working on this system and | 679 // Returns true if the high resolution clock is working on this system and |
660 // Now() will return high resolution values. Note that, on systems where the | 680 // Now() will return high resolution values. Note that, on systems where the |
661 // high resolution clock works but is deemed inefficient, the low resolution | 681 // high resolution clock works but is deemed inefficient, the low resolution |
662 // clock will be used instead. | 682 // clock will be used instead. |
663 static bool IsHighResolution(); | 683 static bool IsHighResolution(); |
664 | 684 |
665 // Returns true if ThreadNow() is supported on this system. | |
666 static bool IsThreadNowSupported() { | |
667 #if (defined(_POSIX_THREAD_CPUTIME) && (_POSIX_THREAD_CPUTIME >= 0)) || \ | |
668 (defined(OS_MACOSX) && !defined(OS_IOS)) || defined(OS_ANDROID) | |
669 return true; | |
670 #else | |
671 return false; | |
672 #endif | |
673 } | |
674 | |
675 // Returns thread-specific CPU-time on systems that support this feature. | |
676 // Needs to be guarded with a call to IsThreadNowSupported(). Use this timer | |
677 // to (approximately) measure how much time the calling thread spent doing | |
678 // actual work vs. being de-scheduled. May return bogus results if the thread | |
679 // migrates to another CPU between two calls. | |
680 // | |
681 // WARNING: The returned value might NOT have the same origin as Now(). Do not | |
682 // perform math between TimeTicks values returned by Now() and ThreadNow() and | |
683 // expect meaningful results. | |
684 // TODO(miu): Since the timeline of these values is different, the values | |
685 // should be of a different type. | |
686 static TimeTicks ThreadNow(); | |
687 | |
688 // Returns the current system trace time or, if not available on this | |
689 // platform, a high-resolution time value; or a low-resolution time value if | |
690 // neither are avalable. On systems where a global trace clock is defined, | |
691 // timestamping TraceEvents's with this value guarantees synchronization | |
692 // between events collected inside chrome and events collected outside | |
693 // (e.g. kernel, X server). | |
694 // | |
695 // WARNING: The returned value might NOT have the same origin as Now(). Do not | |
696 // perform math between TimeTicks values returned by Now() and | |
697 // NowFromSystemTraceTime() and expect meaningful results. | |
698 // TODO(miu): Since the timeline of these values is different, the values | |
699 // should be of a different type. | |
700 static TimeTicks NowFromSystemTraceTime(); | |
701 | |
702 #if defined(OS_WIN) | 685 #if defined(OS_WIN) |
703 // Translates an absolute QPC timestamp into a TimeTicks value. The returned | 686 // Translates an absolute QPC timestamp into a TimeTicks value. The returned |
704 // value has the same origin as Now(). Do NOT attempt to use this if | 687 // value has the same origin as Now(). Do NOT attempt to use this if |
705 // IsHighResolution() returns false. | 688 // IsHighResolution() returns false. |
706 static TimeTicks FromQPCValue(LONGLONG qpc_value); | 689 static TimeTicks FromQPCValue(LONGLONG qpc_value); |
707 #endif | 690 #endif |
708 | 691 |
709 // Get the TimeTick value at the time of the UnixEpoch. This is useful when | 692 // Get the TimeTick value at the time of the UnixEpoch. This is useful when |
710 // you need to relate the value of TimeTicks to a real time and date. | 693 // you need to relate the value of TimeTicks to a real time and date. |
711 // Note: Upon first invocation, this function takes a snapshot of the realtime | 694 // Note: Upon first invocation, this function takes a snapshot of the realtime |
(...skipping 19 matching lines...) Expand all Loading... | |
731 | 714 |
732 // Please use Now() to create a new object. This is for internal use | 715 // Please use Now() to create a new object. This is for internal use |
733 // and testing. | 716 // and testing. |
734 explicit TimeTicks(int64 us) : TimeBase(us) { | 717 explicit TimeTicks(int64 us) : TimeBase(us) { |
735 } | 718 } |
736 }; | 719 }; |
737 | 720 |
738 // For logging use only. | 721 // For logging use only. |
739 BASE_EXPORT std::ostream& operator<<(std::ostream& os, TimeTicks time_ticks); | 722 BASE_EXPORT std::ostream& operator<<(std::ostream& os, TimeTicks time_ticks); |
740 | 723 |
724 // ThreadTicks ---------------------------------------------------------------- | |
725 | |
726 // Represents a clock, specific to a particular thread, than runs only while the | |
727 // thread is running. | |
728 class BASE_EXPORT ThreadTicks : public time_internal::TimeBase<ThreadTicks> { | |
729 public: | |
730 ThreadTicks() : TimeBase(0) { | |
731 } | |
732 | |
733 // Returns true if ThreadTicks::Now() is supported on this system. | |
734 static bool IsSupported() { | |
735 #if (defined(_POSIX_THREAD_CPUTIME) && (_POSIX_THREAD_CPUTIME >= 0)) || \ | |
736 (defined(OS_MACOSX) && !defined(OS_IOS)) || defined(OS_ANDROID) | |
737 return true; | |
738 #else | |
739 return false; | |
740 #endif | |
741 } | |
742 | |
743 // Returns thread-specific CPU-time on systems that support this feature. | |
744 // Needs to be guarded with a call to IsSupported(). Use this timer | |
745 // to (approximately) measure how much time the calling thread spent doing | |
746 // actual work vs. being de-scheduled. May return bogus results if the thread | |
747 // migrates to another CPU between two calls. | |
748 static ThreadTicks Now(); | |
749 | |
750 private: | |
751 friend class time_internal::TimeBase<ThreadTicks>; | |
752 | |
753 // Please use Now() to create a new object. This is for internal use | |
754 // and testing. | |
755 explicit ThreadTicks(int64 us) : TimeBase(us) { | |
756 } | |
757 }; | |
758 | |
759 // For logging use only. | |
760 BASE_EXPORT std::ostream& operator<<(std::ostream& os, ThreadTicks time_ticks); | |
761 | |
762 // TraceTicks ---------------------------------------------------------------- | |
763 | |
764 // Represents high-resolution system trace clock time. | |
765 class BASE_EXPORT TraceTicks : public time_internal::TimeBase<TraceTicks> { | |
dsinclair
2015/05/29 14:38:10
How is a TraceTick different from a normal TimeTic
miu
2015/05/29 17:34:25
It is generated from a different clock source on m
| |
766 public: | |
767 // We define this even without OS_CHROMEOS for seccomp sandbox testing. | |
768 #if defined(OS_LINUX) | |
769 // Force definition of the system trace clock; it is a chromeos-only api | |
770 // at the moment and surfacing it in the right place requires mucking | |
771 // with glibc et al. | |
772 static const clockid_t kClockSystemTrace = 11; | |
773 #endif | |
774 | |
775 TraceTicks() : TimeBase(0) { | |
776 } | |
777 | |
778 // Returns the current system trace time or, if not available on this | |
779 // platform, a high-resolution time value; or a low-resolution time value if | |
780 // neither are avalable. On systems where a global trace clock is defined, | |
781 // timestamping TraceEvents's with this value guarantees synchronization | |
782 // between events collected inside chrome and events collected outside | |
783 // (e.g. kernel, X server). | |
784 // | |
785 // On some platforms, the clock source used for tracing can vary depending on | |
786 // hardware and/or kernel support. Do not make any assumptions without | |
787 // consulting the documentation for this functionality in the time_win.cc, | |
788 // time_posix.cc, etc. files. | |
789 // | |
790 // NOTE: This is only meant to be used by the event tracing infrastructure, | |
791 // and by outside code modules in special circumstances. Please be sure to | |
792 // consult a base/trace_event/OWNER before committing any new code that uses | |
793 // this. | |
794 static TraceTicks Now(); | |
795 | |
796 private: | |
797 friend class time_internal::TimeBase<TraceTicks>; | |
798 | |
799 // Please use Now() to create a new object. This is for internal use | |
800 // and testing. | |
801 explicit TraceTicks(int64 us) : TimeBase(us) { | |
802 } | |
803 }; | |
804 | |
805 // For logging use only. | |
806 BASE_EXPORT std::ostream& operator<<(std::ostream& os, TraceTicks time_ticks); | |
807 | |
741 } // namespace base | 808 } // namespace base |
742 | 809 |
743 #endif // BASE_TIME_TIME_H_ | 810 #endif // BASE_TIME_TIME_H_ |
OLD | NEW |