Allow callers of TimeSource::GetWallClockTime() to suspend time.

media/base/time_source.h

Index: media/base/time_source.h
diff --git a/media/base/time_source.h b/media/base/time_source.h
index d025de2a6ccb53cdebee6b1f71dd78eab6b11c50..a5ebeefd34056a492557378a7ff919389bdd5d05 100644
--- a/media/base/time_source.h
+++ b/media/base/time_source.h
@@ -5,6 +5,7 @@
 #ifndef MEDIA_BASE_TIME_SOURCE_H_
 #define MEDIA_BASE_TIME_SOURCE_H_
 
+#include "base/callback.h"
 #include "base/time/time.h"
 #include "media/base/media_export.h"
 
@@ -13,6 +14,9 @@ namespace media {
 // A TimeSource is capable of providing the current media time.
 class MEDIA_EXPORT TimeSource {
  public:
+  // Used to convert a media timestamp into a wall clock timestamp.
+  using WallClockTimeCB = base::Callback<base::TimeTicks(base::TimeDelta, int)>;
+
   TimeSource() {}
   virtual ~TimeSource() {}
 
@@ -26,7 +30,7 @@ class MEDIA_EXPORT TimeSource {
 
   // Updates the current playback rate. It is expected that values from
   // CurrentMediaTime() will eventually reflect the new playback rate (e.g., the
-  // media time will advance at half speed if the rate was set to 0.5f).
+  // media time will advance at half speed if the rate was set to 0.5).
   virtual void SetPlaybackRate(double playback_rate) = 0;
 
   // Sets the media time to start ticking from. Only valid to call while the
@@ -50,7 +54,31 @@ class MEDIA_EXPORT TimeSource {
   // |media_time| values behind the current media time may be significantly
   // incorrect if the playback rate has changed recently. The only guarantee is
   // that the returned time will be less than the current wall clock time.
-  virtual base::TimeTicks GetWallClockTime(base::TimeDelta media_time) = 0;
+  //
+  // Clients which need to convert a single timestamp should set |request_flags|
+  // to SINGLE_TIMESTAMP.
+  //
+  // Clients which need to convert multiple timestamps may run into issues of
+  // time monotonicity between timestamps if clock advancement and playback rate
+  // changes are happening on a separate thread.  Such clients should set the
+  // |request_flags| value to SUSPEND_TIME for the first timestamp converted and
+  // RESUME_TIME for the last timestamp to convert.  Timestamps in between must
+  // set TIME_IS_SUSPENDED.  These flags guarantee that the time state will not
+  // change between calls.  Time may not be suspended when stopped, so if a null
+  // TimeTicks value is returned, it is not necessary to send RESUME_TIME.
+  //
+  // Warning: Suspending the time state may stall other threads, including the
+  // audio thread, do not suspend time for beyond very brief intervals.  Unless
+  // the returned TimeTicks value is null, callers which send SUSPEND_TIME must
+  // _always_ send RESUME_TIME at a later time.
+  enum RequestFlags {
+    TIME_IS_SUSPENDED = 0,
+    SUSPEND_TIME = 0x1,
+    RESUME_TIME = 0x2,
+    SINGLE_TIMESTAMP = SUSPEND_TIME | RESUME_TIME
+  };
+  virtual base::TimeTicks GetWallClockTime(base::TimeDelta media_time,
+                                           int request_flags) = 0;
 };
 
 }  // namespace media