blob: 88c2616edcfc5490ec997af2fa850292959594c2 [file] [log] [blame]
// 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
*
* This reference describes the Dart embedding API for tools. Tools include
* a debugger, service protocol, and timeline.
*
* NOTE: The APIs described in this file are unstable and subject to change.
*
* This reference is generated from the header include/dart_tools_api.h.
*/
/*
* ========
* Debugger
* ========
*/
typedef struct _Dart_Breakpoint* Dart_Breakpoint;
typedef struct _Dart_StackTrace* Dart_StackTrace;
typedef struct _Dart_ActivationFrame* Dart_ActivationFrame;
/**
* An id used to uniquely represent an Isolate in the debugger wire protocol
* messages.
*/
typedef Dart_Port Dart_IsolateId;
/**
* ILLEGAL_ISOLATE_ID is a number guaranteed never to be associated with a
* valid isolate.
*/
#define ILLEGAL_ISOLATE_ID ILLEGAL_PORT
/**
* Null value for breakpoint id. Guaranteed never to be associated
* with a valid breakpoint.
*/
#define ILLEGAL_BREAKPOINT_ID 0
typedef void Dart_ExceptionThrownHandler(Dart_IsolateId isolate_id,
Dart_Handle exception_object,
Dart_StackTrace stack_trace);
typedef enum {
kCreated = 0,
kInterrupted,
kShutdown,
} Dart_IsolateEvent;
/**
* Represents a location in Dart code.
*/
typedef struct {
Dart_Handle script_url; // Url (string) of the script.
int32_t library_id; // Library in which the script is loaded.
int32_t token_pos; // Code address.
} Dart_CodeLocation;
typedef void Dart_IsolateEventHandler(Dart_IsolateId isolate_id,
Dart_IsolateEvent kind);
typedef void Dart_PausedEventHandler(Dart_IsolateId isolate_id,
intptr_t bp_id,
const Dart_CodeLocation& location);
typedef void Dart_BreakpointResolvedHandler(Dart_IsolateId isolate_id,
intptr_t bp_id,
const Dart_CodeLocation& location);
/**
* Caches a given \object and returns an object id. The object id is only
* valid while the VM is paused. The cache is invalidated when the VM
* resumes.
*
* Requires there to be a current isolate.
*
* Returns an id >= 0 on success, or -1 if there is an error.
*/
DART_EXPORT intptr_t Dart_CacheObject(Dart_Handle object_in);
/**
* Returns a cached object given the \obj_id.
*
* Requires there to be a current isolate.
*/
DART_EXPORT Dart_Handle Dart_GetCachedObject(intptr_t obj_id);
/**
* Returns a list of ids (integers) of all the libraries loaded in the
* current isolate.
*
* Requires there to be a current isolate.
*
* \return A handle to a list of library ids.
*/
DART_EXPORT Dart_Handle Dart_GetLibraryIds();
/**
* Returns true if the debugger can step into code of the given library.
*
* Requires there to be a current isolate.
*
* \return A handle to the True object if no error occurs.
*/
DART_EXPORT Dart_Handle Dart_GetLibraryDebuggable(intptr_t library_id,
bool* is_debuggable);
/**
* Requets that debugging be enabled for the given library.
*
* Requires there to be a current isolate.
*
* \return A handle to the True object if no error occurs.
*/
DART_EXPORT Dart_Handle Dart_SetLibraryDebuggable(intptr_t library_id,
bool is_debuggable);
/**
* Returns a list of urls (strings) of all the scripts loaded in the
* given library.
*
* Requires there to be a current isolate.
*
* \return A handle to a list of string handles.
*/
DART_EXPORT Dart_Handle Dart_GetScriptURLs(Dart_Handle library_url);
/**
* Returns a string containing the source code of the given script
* in the given library.
*
* Requires there to be a current isolate.
*
* \return A handle to string containing the source text if no error
* occurs.
*/
DART_EXPORT Dart_Handle Dart_ScriptGetSource(
intptr_t library_id,
Dart_Handle script_url_in);
/**
* Returns an array containing line number and token offset info
* for the given script.
*
* Returns an array of numbers. Null values indicate the beginning of
* a new line. The first number after null is the line number.
* The line number is followed by pairs of numbers, with the first value
* being the "token offset" and the second value being the column number
* of the token.
* The "token offset" is a value that is used to indicate a location
* in code, similarly to a "PC" address.
* Source lines with no tokens are omitted.
*
* Requires there to be a current isolate.
*
* \return A handle to an array or an error object.
*/
DART_EXPORT Dart_Handle Dart_ScriptGetTokenInfo(
intptr_t library_id,
Dart_Handle script_url_in);
/**
* Returns a string containing a generated source code of the given script
* in the given library. This is essentially used to pretty print dart code
* generated from any tool (e.g: dart2dart).
*
* Requires there to be a current isolate.
*
* \return A handle to string containing the source text if no error
* occurs.
*/
DART_EXPORT Dart_Handle Dart_GenerateScriptSource(Dart_Handle library_url_in,
Dart_Handle script_url_in);
/**
* Sets a breakpoint at line \line_number in \script_url, or the closest
* following line (within the same function) where a breakpoint can be set.
*
* Requires there to be a current isolate.
*
* \return A handle containing the breakpoint id, which is an integer
* value, or an error object if a breakpoint could not be set.
*/
DART_EXPORT Dart_Handle Dart_SetBreakpoint(
Dart_Handle script_url,
intptr_t line_number);
/**
* Deletes the breakpoint with the given id \pb_id.
*
* Requires there to be a current isolate.
*
* \return A handle to the True object if no error occurs.
*/
DART_EXPORT Dart_Handle Dart_RemoveBreakpoint(intptr_t bp_id);
/**
* Get the script URL of the breakpoint with the given id \pb_id.
*
* Requires there to be a current isolate.
*
* \return A handle to the URL (string) of the script, or an error
* object.
*/
DART_EXPORT Dart_Handle Dart_GetBreakpointURL(intptr_t bp_id);
/**
* Get the line number of the breakpoint with the given id \pb_id.
*
* Requires there to be a current isolate.
*
* \return A handle to the line number (integer) of the script,
* or an error object.
*/
DART_EXPORT Dart_Handle Dart_GetBreakpointLine(intptr_t bp_id);
/**
* Sets a one-time breakpoint at the entry of the given function.
* If class_name is the empty string, looks for a library function
* with the given name.
*
* Requires there to be a current isolate.
*
* \return A handle containing the breakpoint id, which is an integer
* value, or an error object if a breakpoint could not be set.
*/
DART_EXPORT Dart_Handle Dart_SetBreakpointAtEntry(
Dart_Handle library,
Dart_Handle class_name,
Dart_Handle function_name);
/**
* Sets a breakpoint at the entry of the given function. If class_name
* is the empty string, looks for a library function with the given
* name.
*
* Requires there to be a current isolate.
*
* \return A handle to the True object if no error occurs.
*/
DART_EXPORT Dart_Handle Dart_OneTimeBreakAtEntry(
Dart_Handle library,
Dart_Handle class_name,
Dart_Handle function_name);
/**
* Can be called from the breakpoint handler. Sets the debugger to
* single step mode.
*
* Requires there to be a current isolate.
*/
DART_EXPORT Dart_Handle Dart_SetStepOver();
/**
* Can be called from the breakpoint handler. Causes the debugger to
* break after at the beginning of the next function call.
*
* Requires there to be a current isolate.
*/
DART_EXPORT Dart_Handle Dart_SetStepInto();
/**
* Can be called from the breakpoint handler. Causes the debugger to
* break after returning from the current Dart function.
*
* Requires there to be a current isolate.
*/
DART_EXPORT Dart_Handle Dart_SetStepOut();
/**
* Installs a handler callback function that gets called by the VM
* when a breakpoint location has been reached or when stepping.
*
* Requires there to be a current isolate.
*/
DART_EXPORT void Dart_SetPausedEventHandler(
Dart_PausedEventHandler handler);
/**
* Installs a callback function that gets called by the VM when
* a breakpoint has been resolved to an actual url and line number.
*
* Requires there to be a current isolate.
*/
DART_EXPORT void Dart_SetBreakpointResolvedHandler(
Dart_BreakpointResolvedHandler handler);
/**
* Installs a callback function that gets called by the VM when
* an exception has been thrown.
*
* Requires there to be a current isolate.
*/
DART_EXPORT void Dart_SetExceptionThrownHandler(
Dart_ExceptionThrownHandler handler);
/**
* Installs a callback function that gets called by the VM when
* an isolate event happens, e.g:
* - creation of a new isolate
* - shutdown of an isolate
* - interruption of an isolate
*/
DART_EXPORT void Dart_SetIsolateEventHandler(Dart_IsolateEventHandler handler);
// On which exceptions to pause.
typedef enum {
kNoPauseOnExceptions = 1,
kPauseOnUnhandledExceptions,
kPauseOnAllExceptions,
kInvalidExceptionPauseInfo
} Dart_ExceptionPauseInfo;
/**
* Define on which exceptions the debugger pauses.
*
* Requires there to be a current isolate.
*/
DART_EXPORT Dart_Handle Dart_SetExceptionPauseInfo(
Dart_ExceptionPauseInfo pause_info);
/**
* Returns on which exceptions the debugger pauses.
*
* Requires there to be a current isolate.
*/
DART_EXPORT Dart_ExceptionPauseInfo Dart_GetExceptionPauseInfo();
/**
* Returns in \trace the current stack trace, or NULL if the
* VM is not paused.
*
* Requires there to be a current isolate.
*
* \return A valid handle if no error occurs during the operation.
*/
DART_EXPORT Dart_Handle Dart_GetStackTrace(Dart_StackTrace* trace);
/**
* Returns in \trace the stack trace associated with the error given in \handle.
*
* Requires there to be a current isolate.
*
* \return A valid handle if no error occurs during the operation.
*/
DART_EXPORT Dart_Handle Dart_GetStackTraceFromError(Dart_Handle error,
Dart_StackTrace* trace);
/**
* Returns in \length the number of activation frames in the given
* stack trace.
*
* Requires there to be a current isolate.
*
* \return A handle to the True object if no error occurs.
*/
DART_EXPORT Dart_Handle Dart_StackTraceLength(
Dart_StackTrace trace,
intptr_t* length);
/**
* Returns in \frame the activation frame with index \frame_index.
* The activation frame at the top of stack has index 0.
*
* Requires there to be a current isolate.
*
* \return A handle to the True object if no error occurs.
*/
DART_EXPORT Dart_Handle Dart_GetActivationFrame(
Dart_StackTrace trace,
int frame_index,
Dart_ActivationFrame* frame);
/**
* Returns information about the given activation frame.
* \function_name receives a string handle with the qualified
* function name.
* \script_url receives a string handle with the url of the
* source script that contains the frame's function.
* \line_number receives the line number in the script.
* \col_number receives the column number in the script, or -1 if column
* information is not available
*
* Any or all of the out parameters above may be NULL.
*
* Requires there to be a current isolate.
*
* \return A valid handle if no error occurs during the operation.
*/
DART_EXPORT Dart_Handle Dart_ActivationFrameInfo(
Dart_ActivationFrame activation_frame,
Dart_Handle* function_name,
Dart_Handle* script_url,
intptr_t* line_number,
intptr_t* column_number);
/**
* Returns code location of the given activation frame.
*
* \function_name receives a string handle with the qualified
* function name.
* \function receives a handle to the function.
* \location.script_url receives a string handle with the url of
* the source script that contains the frame's function.
* Receives a null handle if there is no textual location
* that corresponds to the frame, e.g. for implicitly
* generated constructors.
* \location.library_id receives the id of the library in which the
* function in this frame is defined.
* \location.token_pos receives the token position in the script.
*
* Any of the out parameters above may be NULL.
*
* Requires there to be a current isolate.
*
* \return A handle to the True object if no error occurs.
* A handle to the False object if there is no text
* position for the frame.
*/
DART_EXPORT Dart_Handle Dart_ActivationFrameGetLocation(
Dart_ActivationFrame activation_frame,
Dart_Handle* function_name,
Dart_Handle* function,
Dart_CodeLocation* location);
/**
* Returns frame pointer of the given activation frame.
*
* \frame_pointer receives the frame pointer for the frame.
*
* Requires there to be a current isolate.
*
* \return A handle to the True object if no error occurs.
*/
DART_EXPORT Dart_Handle Dart_ActivationFrameGetFramePointer(
Dart_ActivationFrame activation_frame,
uintptr_t* frame_pointer);
/**
* Returns an array containing all the local variable names and values of
* the given \activation_frame.
*
* Requires there to be a current isolate.
*
* \return A handle to an array containing variable names and
* corresponding values. The array is empty if the activation frame has
* no variables. If non-empty, variable names are at array offsets 2*n,
* values at offset 2*n+1.
*/
DART_EXPORT Dart_Handle Dart_GetLocalVariables(
Dart_ActivationFrame activation_frame);
/**
* Returns origin class of a function.
*
* Requires there to be a current isolate.
*
* \return Returns the class id (a handle to an integer) of the class in
* which \function is defined. Returns a null handle if \function is defined
* at the top level. Returns an error object otherwise.
*/
DART_EXPORT Dart_Handle Dart_GetFunctionOrigin(Dart_Handle function);
/**
* Returns an array containing all the global variable names and values of
* the library with given \library_id.
*
* Requires there to be a current isolate.
*
* \return A handle to an array containing variable names and
* corresponding values. Variable names are at array offsets 2*n,
* values at offset 2*n+1.
*/
DART_EXPORT Dart_Handle Dart_GetGlobalVariables(intptr_t library_id);
/**
* Execute the expression given in string \expr in the context
* of stack frame \activation_frame.
*/
DART_EXPORT Dart_Handle Dart_ActivationFrameEvaluate(
Dart_ActivationFrame activation_frame,
Dart_Handle expr_in);
/**
* Execute the expression given in string \expr in the context
* of \target.
*
* Requires there to be a current isolate.
*
* The expression is evaluated in the context of \target.
* If \target is a Dart object, the expression is evaluated as if
* it were an instance method of the class of the object.
* If \target is a Class, the expression is evaluated as if it
* were a static method of that class.
* If \target is a Library, the expression is evaluated as if it
* were a top-level function in that library.
*
* \return A handle to the computed value, or an error object if
* the compilation of the expression fails, or if the evaluation throws
* an error.
*/
DART_EXPORT Dart_Handle Dart_EvaluateExpr(Dart_Handle target,
Dart_Handle expr);
/**
* Returns the class of the given \object.
*
* Requires there to be a current isolate.
*
* \return A handle to the class object.
*/
DART_EXPORT Dart_Handle Dart_GetObjClass(Dart_Handle object);
/**
* Returns in \class_id the class id of the given \object. The id is valid
* for the lifetime of the isolate.
*
* Requires there to be a current isolate.
*
* \return True if no error occurs.
*/
DART_EXPORT Dart_Handle Dart_GetObjClassId(Dart_Handle object,
intptr_t* class_id);
/**
* Returns the supertype of the given instantiated type \cls.
*
* Requires there to be a current isolate.
*
* \return A handle to the type object.
*/
DART_EXPORT Dart_Handle Dart_GetSupertype(Dart_Handle type);
/**
* Returns handle to class with class id \class_id.
*
* Requires there to be a current isolate.
*
* \return A handle to the class if no error occurs.
*/
DART_EXPORT Dart_Handle Dart_GetClassFromId(intptr_t class_id);
/**
* Returns info about the given class \cls_id.
*
* \param class_name receives handle to class name (string) if non-null.
* \param library receives handle to library in which the class
* is defined, if non-null.
* \param super_class_id receives the class id to the super class of
* \cls_id if non-null.
* \param static_fields If non-null, receives an array containing field
* names and values of static fields of the class. Names are
* at array offsets 2*n, values at offset 2*n+1.
*
* Requires there to be a current isolate.
*
* \return A handle to the value true if no error occurs.
*/
DART_EXPORT Dart_Handle Dart_GetClassInfo(intptr_t class_id,
Dart_Handle* class_name,
intptr_t* library_id,
intptr_t* super_class_id,
Dart_Handle* static_fields);
/** Returns info about the given closure \closure.
*
* \param name receives handle to closure name (string).
* Receives a null handle if the closure is anonymous.
* \param signature receives handle to closure signature (string).
* \param location.script_url receives a string handle with the url of
* the source script that contains the closure.
* Receives a null handle if there is no textual location
* that corresponds to the fucntion.
* \param location.library_id receives the id of the library in which the
* function in this frame is defined.
* \param location.token_pos receives the token position in the script.
*
* \return A handle to the value true if no error occurs.
*/
DART_EXPORT Dart_Handle Dart_GetClosureInfo(Dart_Handle closure,
Dart_Handle* name,
Dart_Handle* signature,
Dart_CodeLocation* location);
/**
* Returns an array containing all instance field names and values of
* the given \object.
*
* Requires there to be a current isolate.
*
* \return A handle to an array containing field names and
* corresponding field values. The array is empty if the object has
* no fields. If non-empty, field names are at array offsets 2*n,
* values at offset 2*n+1. Field values may also be a handle to an
* error object if an error was encountered evaluating the field.
*/
DART_EXPORT Dart_Handle Dart_GetInstanceFields(Dart_Handle object);
/**
* Returns an array containing all static field names and values of
* the given type \target.
*
* Requires there to be a current isolate.
*
* \return A handle to an array containing field names and
* corresponding field values. The array is empty if the class has
* no static fields. If non-empty, field names are at array offsets 2*n,
* values at offset 2*n+1. Field values may also be a handle to an
* error object if an error was encountered evaluating the field.
*/
DART_EXPORT Dart_Handle Dart_GetStaticFields(Dart_Handle target);
/**
* Returns a handle to the library \library_id.
*
* Requires there to be a current isolate.
*
* \return A library handle if the id is valid.
*/
DART_EXPORT Dart_Handle Dart_GetLibraryFromId(intptr_t library_id);
/**
* Returns in \library_id the library id of the given \library.
*
* \return A valid handle if no error occurs during the operation.
*/
DART_EXPORT Dart_Handle Dart_LibraryId(Dart_Handle library,
intptr_t* library_id);
/**
* Returns an array containing all variable names and values of
* the given library \library_id.
*
* Requires there to be a current isolate.
*
* \return A handle to an array containing variable names and
* corresponding values. The array is empty if the library has
* no variables. If non-empty, variable names are at array offsets 2*n,
* values at offset 2*n+1. Variable values may also be a handle to an
* error object if an error was encountered evaluating the value.
*/
DART_EXPORT Dart_Handle Dart_GetLibraryFields(intptr_t library_id);
/**
* Returns an array containing all imported libraries of
* the given library \library_id.
*
* Requires there to be a current isolate.
*
* \return A handle to an array containing prefix names and
* library ids. The array is empty if the library has
* no imports. If non-empty, import prefixes are at array offsets 2*n,
* corresponding library ids at offset 2*n+1. Prefixes may be null
* which indicates the respective library has been imported without
* a prefix.
*/
DART_EXPORT Dart_Handle Dart_GetLibraryImports(intptr_t library_id);
/**
* Returns the url of the library \library_id.
*
* Requires there to be a current isolate.
*
* \return A string handle containing the URL of the library.
*/
DART_EXPORT Dart_Handle Dart_GetLibraryURL(intptr_t library_id);
/**
* Returns the isolate object corresponding to the isolate id.
*
* \return The Dart_Isolate object corresponding to the isolate id.
* If the specified id is invalid NULL is returned.
*/
DART_EXPORT Dart_Isolate Dart_GetIsolate(Dart_IsolateId isolate_id);
/**
* Returns the isolate id for an isolate.
*
* \return The Dart_IsolateId value corresponding to the isolate.
*/
DART_EXPORT Dart_IsolateId Dart_GetIsolateId(Dart_Isolate isolate);
/*
* =======
* Service
* =======
*/
/**
* A service request callback function.
*
* These callbacks, registered by the embedder, are called when the VM receives
* a service request it can't handle and the service request command name
* matches one of the embedder registered handlers.
*
* \param method The rpc method name.
* \param param_keys Service requests can have key-value pair parameters. The
* keys and values are flattened and stored in arrays.
* \param param_values The values associated with the keys.
* \param num_params The length of the param_keys and param_values arrays.
* \param user_data The user_data pointer registered with this handler.
*
* \return Returns a C string containing a valid JSON object. The returned
* pointer will be freed by the VM by calling free.
*/
typedef const char* (*Dart_ServiceRequestCallback)(
const char* method,
const char** param_keys,
const char** param_values,
intptr_t num_params,
void* user_data);
/**
* Register a Dart_ServiceRequestCallback to be called to handle
* requests for the named rpc on a specific isolate. The callback will
* be invoked with the current isolate set to the request target.
*
* \param method The name of the method that this callback is responsible for.
* \param callback The callback to invoke.
* \param user_data The user data passed to the callback.
*
* NOTE: If multiple callbacks with the same name are registered, only
* the last callback registered will be remembered.
*/
DART_EXPORT void Dart_RegisterIsolateServiceRequestCallback(
const char* method,
Dart_ServiceRequestCallback callback,
void* user_data);
/**
* Register a Dart_ServiceRequestCallback to be called to handle
* requests for the named rpc. The callback will be invoked without a
* current isolate.
*
* \param method The name of the command that this callback is responsible for.
* \param callback The callback to invoke.
* \param user_data The user data passed to the callback.
*
* NOTE: If multiple callbacks with the same name are registered, only
* the last callback registered will be remembered.
*/
DART_EXPORT void Dart_RegisterRootServiceRequestCallback(
const char* method,
Dart_ServiceRequestCallback callback,
void* user_data);
/*
* ========
* Event Streams
* ========
*/
/**
* A callback invoked when the VM service gets a request to listen to
* some stream.
*
* \return Returns true iff the embedder supports the named stream id.
*/
typedef bool (*Dart_ServiceStreamListenCallback)(const char* stream_id);
/**
* A callback invoked when the VM service gets a request to cancel
* some stream.
*/
typedef void (*Dart_ServiceStreamCancelCallback)(const char* stream_id);
/**
* Adds VM service stream callbacks.
*
* \param listen_callback A function pointer to a listen callback function.
* A listen callback function should not be already set when this function
* is called. A NULL value removes the existing listen callback function
* if any.
*
* \param cancel_callback A function pointer to a cancel callback function.
* A cancel callback function should not be already set when this function
* is called. A NULL value removes the existing cancel callback function
* if any.
*
* \return Success if the callbacks were added. Otherwise, returns an
* error handle.
*/
DART_EXPORT Dart_Handle Dart_SetServiceStreamCallbacks(
Dart_ServiceStreamListenCallback listen_callback,
Dart_ServiceStreamCancelCallback cancel_callback);
/**
* Sends a data event to clients of the VM Service.
*
* A data event is used to pass an array of bytes to subscribed VM
* Service clients. For example, in the standalone embedder, this is
* function used to provide WriteEvents on the Stdout and Stderr
* streams.
*
* If the embedder passes in a stream id for which no client is
* subscribed, then the event is ignored.
*
* \param stream_id The id of the stream on which to post the event.
*
* \param event_kind A string identifying what kind of event this is.
* For example, 'WriteEvent'.
*
* \param bytes A pointer to an array of bytes.
*
* \param bytes_length The length of the byte array.
*
* \return Success if the arguments are well formed. Otherwise, returns an
* error handle.
*/
DART_EXPORT Dart_Handle Dart_ServiceSendDataEvent(const char* stream_id,
const char* event_kind,
const uint8_t* bytes,
intptr_t bytes_length);
/*
* ========
* Timeline
* ========
*/
/**
* Returns a timestamp in microseconds. This timestamp is suitable for
* passing into the timeline system.
*
* \return A timestamp that can be passed to the timeline system.
*/
DART_EXPORT int64_t Dart_TimelineGetMicros();
/** 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 Dart provided events */
#define DART_TIMELINE_STREAM_DART (1 << 2)
/** Timeline stream for embedder provided events */
#define DART_TIMELINE_STREAM_EMBEDDER (1 << 3)
/** Timeline stream for GC events */
#define DART_TIMELINE_STREAM_GC (1 << 4)
/** Timeline stream for isolate events */
#define DART_TIMELINE_STREAM_ISOLATE (1 << 5)
/** Timeline stream for VM events */
#define DART_TIMELINE_STREAM_VM (1 << 6)
/** Enable all timeline stream recording for an isolate */
#define DART_TIMELINE_STREAM_ALL (DART_TIMELINE_STREAM_API | \
DART_TIMELINE_STREAM_COMPILER | \
DART_TIMELINE_STREAM_DART | \
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);
/**
* Start recording timeline events for the entire VM (including all isolates).
*
* NOTE: When enabled, the global flag, will override the per-isolate flag.
*
* \param stream_mask A bitmask of streams that should be recorded.
*
* NOTE: Calling with 0 disables recording of all streams.
*/
DART_EXPORT void Dart_GlobalTimelineSetRecordedStreams(int64_t stream_mask);
typedef enum {
/** Indicates a new stream is being output */
Dart_StreamConsumer_kStart = 0,
/** Data for the current stream */
Dart_StreamConsumer_kData = 1,
/** Indicates stream is finished */
Dart_StreamConsumer_kFinish = 2,
} Dart_StreamConsumer_State;
/**
* A stream consumer callback function.
*
* This function will be called repeatedly until there is no more data in a
* stream and there are no more streams.
*
* \param state Indicates a new stream, data, or a finished stream.
* \param stream_name A name for this stream. Not guaranteed to be meaningful.
* \param buffer A pointer to the stream data.
* \param buffer_length The number of bytes at buffer that should be consumed.
* \param stream_callback_data The pointer passed in when requesting the stream.
*
* At the start of each stream state will be DART_STREAM_CONSUMER_STATE_START
* and buffer will be NULL.
*
* For each chunk of data the state will be DART_STREAM_CONSUMER_STATE_DATA
* and buffer will not be NULL.
*
* At the end of each stream state will be DART_STREAM_CONSUMER_STATE_FINISH
* and buffer will be NULL.
*/
typedef void (*Dart_StreamConsumer)(
Dart_StreamConsumer_State state,
const char* stream_name,
const uint8_t* buffer,
intptr_t buffer_length,
void* stream_callback_data);
/**
* Get the timeline for the current isolate in trace-event format
*
* \param consumer A Dart_StreamConsumer.
* \param user_data User data passed into consumer.
*
* NOTE: The trace-event format is documented here: https://goo.gl/hDZw5M
*
* \return True if a stream was output.
*/
DART_EXPORT bool Dart_TimelineGetTrace(Dart_StreamConsumer consumer,
void* user_data);
/**
* Get the timeline for entire VM (including all isolates).
*
* NOTE: The timeline retrieved from this API call may not include the most
* recent events.
*
* \param consumer A Dart_StreamConsumer.
* \param user_data User data passed into consumer.
*
* NOTE: The trace-event format is documented here: https://goo.gl/hDZw5M
*
* \return True if a stream was output.
*/
DART_EXPORT bool Dart_GlobalTimelineGetTrace(Dart_StreamConsumer consumer,
void* user_data);
/**
* 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: All timestamps should be acquired from Dart_TimelineGetMicros.
*/
DART_EXPORT Dart_Handle Dart_TimelineDuration(const char* label,
int64_t start_micros,
int64_t end_micros);
/**
* Add an instant timeline event to the embedder stream for the current isolate.
*
* \param label The name of event.
*
* NOTE: All timestamps should be acquired from Dart_TimelineGetMicros.
*/
DART_EXPORT Dart_Handle Dart_TimelineInstant(const char* label);
/**
* Adds an asynchronous begin timeline event to the embedder stream for the
* current isolate.
*
* \param label The name of event.
*
* \return Returns an asynchronous id that must be passed to
* Dart_TimelineAsyncInstant and Dart_TimelineAsyncEnd. If the asynchronous
* id is less than 0 the event was not added to the timeline and subsequent
* calls to Dart_TimelineAsyncInstant and Dart_TimelineAsyncEnd will become
* no-ops.
*
* NOTE: All timestamps should be acquired from Dart_TimelineGetMicros.
*/
DART_EXPORT Dart_Handle Dart_TimelineAsyncBegin(const char* label,
int64_t* async_id);
/**
* Adds an asynchronous instant timeline event to the embedder stream for the
* current isolate.
*
* \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_TimelineAsyncInstant(const char* label,
int64_t async_id);
/**
* Adds an asynchronous end timeline event to the embedder stream for the
* current isolate.
*
* \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);
#endif // INCLUDE_DART_TOOLS_API_H_