Add ability for embedder to provide private timeline trace data

runtime/include/dart_tools_api.h

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 #ifndef INCLUDE_DART_TOOLS_API_H_
 #define INCLUDE_DART_TOOLS_API_H_
 
 #include "include/dart_api.h"
 
 /** \mainpage Dart Tools Embedding API Reference
@@ skipping 1060 matching lines @@
  * \param label The name of event.
  *
  * \return Returns an asynchronous id that must be passed to
  * Dart_TimelineAsyncInstant and Dart_TimelineAsyncEnd.
  *
  * NOTE: All timestamps should be acquired from Dart_TimelineGetMicros.
  */
 DART_EXPORT Dart_Handle Dart_TimelineAsyncEnd(const char* label,
                                               int64_t async_id);
 
+
+/**
+ * Called by the VM to let the embedder know when to start recording into their
+ * own timeline implementation. Can be called from any thread.
+ */
+typedef void (*Dart_EmbedderTimelineStartRecording)();
+
+/**
+ * Called by the VM to let the embedder know when to stop recording into their
+ * own timeline implementation. Can be called from any thread.
+ */
+typedef void (*Dart_EmbedderTimelineStopRecording)();
+
+/**
+ * Called by the VM to request data from the embedder's private timeline
+ * implementation. Can be called from any thread and must complete
+ * synchronously.

[yjbanov, 2016/03/10 22:45:16]

I'm not sure Flutter's implementation can complete synchronously. We need to
wait for the log file to be finalized some time after the call to
Dart_EmbedderTimelineStopRecording.

+ *
+ * \param stream_consumer The embedder must only call the stream_consumer with
+ *    the Dart_StreamConsumer_kData state. See Dart_StreamConsumer above.
+ * \param user_data
+ *
+ * \return Returns true on success.
+ *
+ */
+typedef bool (*Dart_EmbedderTimelineGetTimeline)(
+      Dart_StreamConsumer stream_consumer,
+      void* user_data);
+
+
+/**
+ * Sets the embedder timeline callbacks. These callbacks are used by the VM
+ * to notify the embedder of timeline recording state changes and to request
+ * data from the embedder.
+ *
+ * \param start_recording See Dart_EmbedderTimelineStartRecording.
+ * \param stop_recording See Dart_EmbedderTimelineStopRecording.
+ * \param get_timeline See Dart_EmbedderTimelineGetTimeline.
+ *
+ * NOTE: To avoid races, this should be called before Dart_Initialize.
+ */
+DART_EXPORT void Dart_SetEmbedderTimelineCallbacks(
+    Dart_EmbedderTimelineStartRecording start_recording,
+    Dart_EmbedderTimelineStopRecording stop_recording,
+    Dart_EmbedderTimelineGetTimeline get_timeline);

[siva, 2016/03/11 12:56:17]

Does it make sense for any of these callbacks to be NULL?
I am wondering if we could error out if any of the passed in callbacks are NULL,
that would avoid the need to do a NULL check before every invocation of the
callbacks.

+
 #endif  // INCLUDE_DART_TOOLS_API_H_