[vm] Document clock compatibility between Timeline.now and Dart_TimelineGetMicros.
Change-Id: Ife4b5360b9c42221b9dac84014d072f60cd8f11c
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/106720
Commit-Queue: Ryan Macnak <rmacnak@google.com>
Reviewed-by: Ben Konyi <bkonyi@google.com>
Reviewed-by: Siva Annamalai <asiva@google.com>
diff --git a/runtime/include/dart_tools_api.h b/runtime/include/dart_tools_api.h
index 03b38aa..b4985bf 100644
--- a/runtime/include/dart_tools_api.h
+++ b/runtime/include/dart_tools_api.h
@@ -301,7 +301,8 @@
/**
* Returns a timestamp in microseconds. This timestamp is suitable for
- * passing into the timeline system.
+ * passing into the timeline system, and uses the same monotonic clock
+ * as dart:developer's Timeline.now.
*
* \return A timestamp that can be passed to the timeline system.
*/
diff --git a/runtime/vm/service/service.md b/runtime/vm/service/service.md
index 52eea6b..d01f0ef 100644
--- a/runtime/vm/service/service.md
+++ b/runtime/vm/service/service.md
@@ -797,7 +797,8 @@
events.
The _timeOriginMicros_ parameter is the beginning of the time range used to filter
-timeline events.
+timeline events. It uses the same monotonic clock as dart:developer's `Timeline.now`
+and the VM embedding API's `Dart_TimelineGetMicros`.
The _timeExtentMicros_ parameter specifies how large the time range used to filter
timeline events should be.
diff --git a/runtime/vm/service/service_dev.md b/runtime/vm/service/service_dev.md
index 148ee39..bfc5fa9 100644
--- a/runtime/vm/service/service_dev.md
+++ b/runtime/vm/service/service_dev.md
@@ -797,7 +797,8 @@
events.
The _timeOriginMicros_ parameter is the beginning of the time range used to filter
-timeline events.
+timeline events. It uses the same monotonic clock as dart:developer's `Timeline.now`
+and the VM embedding API's `Dart_TimelineGetMicros`.
The _timeExtentMicros_ parameter specifies how large the time range used to filter
timeline events should be.
diff --git a/sdk/lib/developer/timeline.dart b/sdk/lib/developer/timeline.dart
index b18ed93..72d28af 100644
--- a/sdk/lib/developer/timeline.dart
+++ b/sdk/lib/developer/timeline.dart
@@ -166,6 +166,9 @@
/// The current time stamp from the clock used by the timeline. Units are
/// microseconds.
+ ///
+ /// When run on the Dart VM, uses the same monotonic clock as the embedding
+ /// API's `Dart_TimelineGetMicros`.
static int get now => _getTraceClock();
static final List<_SyncBlock> _stack = new List<_SyncBlock>();
}
