| // 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_ |