Add timeline stream control and trace retrieval to the dart embedder api.

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 861 matching lines @@
                                                   const char* event_kind,
                                                   const uint8_t* bytes,
                                                   intptr_t bytes_length);
 
 /*
  * ========
  * Timeline
  * ========
  */
 
+/** Timeline stream for Dart API calls */
+#define DART_TIMELINE_STREAM_API (1 << 0)
+/** Timeline stream for compiler events */
+#define DART_TIMELINE_STREAM_COMPILER (1 << 1)
+/** Timeline stream for embedder provided events */
+#define DART_TIMELINE_STREAM_EMBEDDER (1 << 2)
+/** Timeline stream for GC events */
+#define DART_TIMELINE_STREAM_GC (1 << 3)
+/** Timeline stream for isolate events */
+#define DART_TIMELINE_STREAM_ISOLATE (1 << 4)
+
+/** Enable all timeline stream recording */
+#define DART_TIMELINE_STREAM_ALL (DART_TIMELINE_STREAM_API |                   \
+                                  DART_TIMELINE_STREAM_COMPILER |              \
+                                  DART_TIMELINE_STREAM_EMBEDDER |              \
+                                  DART_TIMELINE_STREAM_GC |                    \
+                                  DART_TIMELINE_STREAM_ISOLATE)
+
+/** Disable all timeline stream recording */
+#define DART_TIMELINE_STREAM_DISABLE 0
+
+/**
+ * Start recording timeline events for the current isolate.
+ *
+ * \param stream_mask A bitmask of streams that should be recorded.
+ *
+ * NOTE: Calling with 0 disables recording of all streams.
+ */
+DART_EXPORT void Dart_TimelineSetRecordedStreams(int64_t stream_mask);
+
+/**
+ * Get the timeline for the current isolate in trace-event format

[turnidge, 2015/08/10 20:21:25]

If there is a convenient description of the trace-event format online, consider
adding a link to it here.

[Cutch, 2015/08/10 20:38:16]

Done.

+ *
+ * \param output The address of the trace buffer output
+ * \param output_length The length of the trace buffer output
+ *
+ * NOTE: output is allocated in the C heap and must be freed by the caller.
+ *
+ * \return True if a trace was output. The outputted trace may be empty.
+ */
+DART_EXPORT bool Dart_TimelineGetTrace(const char** output,
+                                       intptr_t* output_length);
+
 /**
  * Add a duration timeline event to the embedder stream for the current isolate.
  *
  * \param label The name of the event.
  * \param start_micros The start of the duration (in microseconds)
  * \param end_micros The end of the duration (in microseconds)
  *
  * NOTE: On Posix platforms you should use gettimeofday and on Windows platforms
  * you should use GetSystemTimeAsFileTime to get the time values.
  */
@@ skipping 57 matching lines @@
  * \return Returns an asynchronous id that must be passed to
  * Dart_TimelineAsyncInstant and Dart_TimelineAsyncEnd.
  *
  * NOTE: On Posix platforms this call uses gettimeofday and on Windows platforms
  * this call uses GetSystemTimeAsFileTime to get the current time.
  */
 DART_EXPORT Dart_Handle Dart_TimelineAsyncEnd(const char* label,
                                               int64_t async_id);
 
 #endif  // INCLUDE_DART_TOOLS_API_H_