Flutter Engine
The Flutter Engine
Classes | Macros | Typedefs | Enumerations | Functions
dart_tools_api.h File Reference
#include "dart_api.h"

Go to the source code of this file.

Classes

struct  Dart_EmbedderInformation
 
struct  Dart_TimelineRecorderEvent_Argument
 
struct  Dart_TimelineRecorderEvent
 

Macros

#define ILLEGAL_ISOLATE_ID   ILLEGAL_PORT
 
#define ILLEGAL_ISOLATE_GROUP_ID   0
 
#define DART_EMBEDDER_INFORMATION_CURRENT_VERSION   (0x00000001)
 
#define DART_TIMELINE_RECORDER_CURRENT_VERSION   (0x00000002)
 

Typedefs

typedef bool(* Dart_ServiceRequestCallback) (const char *method, const char **param_keys, const char **param_values, intptr_t num_params, void *user_data, const char **json_object)
 
typedef void(* Dart_EmbedderInformationCallback) (Dart_EmbedderInformation *info)
 
typedef bool(* Dart_ServiceStreamListenCallback) (const char *stream_id)
 
typedef void(* Dart_ServiceStreamCancelCallback) (const char *stream_id)
 
typedef bool(* Dart_FileModifiedCallback) (const char *url, int64_t since)
 
typedef void(* Dart_TimelineRecorderCallback) (Dart_TimelineRecorderEvent *event)
 
typedef void(* Dart_HeapSnapshotWriteChunkCallback) (void *context, uint8_t *buffer, intptr_t size, bool is_last)
 

Enumerations

enum  Dart_Timeline_Event_Type {
  Dart_Timeline_Event_Begin , Dart_Timeline_Event_End , Dart_Timeline_Event_Instant , Dart_Timeline_Event_Duration ,
  Dart_Timeline_Event_Async_Begin , Dart_Timeline_Event_Async_End , Dart_Timeline_Event_Async_Instant , Dart_Timeline_Event_Counter ,
  Dart_Timeline_Event_Flow_Begin , Dart_Timeline_Event_Flow_Step , Dart_Timeline_Event_Flow_End
}
 

Functions

DART_EXPORT void Dart_RegisterIsolateServiceRequestCallback (const char *method, Dart_ServiceRequestCallback callback, void *user_data)
 
DART_EXPORT void Dart_RegisterRootServiceRequestCallback (const char *method, Dart_ServiceRequestCallback callback, void *user_data)
 
DART_EXPORT void Dart_SetEmbedderInformationCallback (Dart_EmbedderInformationCallback callback)
 
DART_EXPORT bool Dart_InvokeVMServiceMethod (uint8_t *request_json, intptr_t request_json_length, uint8_t **response_json, intptr_t *response_json_length, char **error)
 
DART_EXPORT char * Dart_SetServiceStreamCallbacks (Dart_ServiceStreamListenCallback listen_callback, Dart_ServiceStreamCancelCallback cancel_callback)
 
DART_EXPORT char * Dart_ServiceSendDataEvent (const char *stream_id, const char *event_kind, const uint8_t *bytes, intptr_t bytes_length)
 
DART_EXPORT char * Dart_SetFileModifiedCallback (Dart_FileModifiedCallback file_modified_callback)
 
DART_EXPORT bool Dart_IsReloading ()
 
DART_EXPORT bool Dart_SetEnabledTimelineCategory (const char *categories)
 
DART_EXPORT int64_t Dart_TimelineGetMicros ()
 
DART_EXPORT int64_t Dart_TimelineGetTicks ()
 
DART_EXPORT int64_t Dart_TimelineGetTicksFrequency ()
 
DART_EXPORT void Dart_RecordTimelineEvent (const char *label, int64_t timestamp0, int64_t timestamp1_or_id, intptr_t flow_id_count, const int64_t *flow_ids, Dart_Timeline_Event_Type type, intptr_t argument_count, const char **argument_names, const char **argument_values)
 
DART_EXPORT void Dart_SetThreadName (const char *name)
 
DART_EXPORT void Dart_SetTimelineRecorderCallback (Dart_TimelineRecorderCallback callback)
 
DART_EXPORT int64_t Dart_IsolateGroupHeapOldUsedMetric (Dart_IsolateGroup group)
 
DART_EXPORT int64_t Dart_IsolateGroupHeapOldCapacityMetric (Dart_IsolateGroup group)
 
DART_EXPORT int64_t Dart_IsolateGroupHeapOldExternalMetric (Dart_IsolateGroup group)
 
DART_EXPORT int64_t Dart_IsolateGroupHeapNewUsedMetric (Dart_IsolateGroup group)
 
DART_EXPORT int64_t Dart_IsolateGroupHeapNewCapacityMetric (Dart_IsolateGroup group)
 
DART_EXPORT int64_t Dart_IsolateGroupHeapNewExternalMetric (Dart_IsolateGroup group)
 
DART_EXPORT Dart_Handle Dart_GetCurrentUserTag ()
 
DART_EXPORT Dart_Handle Dart_GetDefaultUserTag ()
 
DART_EXPORT Dart_Handle Dart_NewUserTag (const char *label)
 
DART_EXPORT Dart_Handle Dart_SetCurrentUserTag (Dart_Handle user_tag)
 
DART_EXPORT DART_WARN_UNUSED_RESULT char * Dart_GetUserTagLabel (Dart_Handle user_tag)
 
DART_EXPORT char * Dart_WriteHeapSnapshot (Dart_HeapSnapshotWriteChunkCallback write, void *context)
 

Macro Definition Documentation

◆ DART_EMBEDDER_INFORMATION_CURRENT_VERSION

#define DART_EMBEDDER_INFORMATION_CURRENT_VERSION   (0x00000001)

Embedder information which can be requested by the VM for internal or reporting purposes.

The pointers in this structure are not going to be cached or freed by the VM.

Definition at line 130 of file dart_tools_api.h.

◆ DART_TIMELINE_RECORDER_CURRENT_VERSION

#define DART_TIMELINE_RECORDER_CURRENT_VERSION   (0x00000002)

Definition at line 428 of file dart_tools_api.h.

◆ ILLEGAL_ISOLATE_GROUP_ID

#define ILLEGAL_ISOLATE_GROUP_ID   0

ILLEGAL_ISOLATE_GROUP_ID is a number guaranteed never to be associated with a valid isolate group.

Definition at line 36 of file dart_tools_api.h.

◆ ILLEGAL_ISOLATE_ID

#define ILLEGAL_ISOLATE_ID   ILLEGAL_PORT

ILLEGAL_ISOLATE_ID is a number guaranteed never to be associated with a valid isolate.

Definition at line 30 of file dart_tools_api.h.

Typedef Documentation

◆ Dart_EmbedderInformationCallback

typedef void(* Dart_EmbedderInformationCallback) (Dart_EmbedderInformation *info)

Callback provided by the embedder that is used by the VM to request information.

Returns
Returns a pointer to a Dart_EmbedderInformation structure. The embedder keeps the ownership of the structure and any field in it. The embedder must ensure that the structure will remain valid until the next invocation of the callback.

Definition at line 148 of file dart_tools_api.h.

◆ Dart_FileModifiedCallback

typedef bool(* Dart_FileModifiedCallback) (const char *url, int64_t since)

A callback which determines whether the file at some url has been modified since some time. If the file cannot be found, true should be returned.

Definition at line 272 of file dart_tools_api.h.

◆ Dart_HeapSnapshotWriteChunkCallback

typedef void(* Dart_HeapSnapshotWriteChunkCallback) (void *context, uint8_t *buffer, intptr_t size, bool is_last)

Callback provided by the caller of Dart_WriteHeapSnapshot which is used to write out chunks of the requested heap snapshot.

Parameters
contextAn opaque context which was passed to Dart_WriteHeapSnapshot together with this callback.
bufferPointer to the buffer containing a chunk of the snapshot. The callback owns the buffer and needs to free it.
sizeNumber of bytes in the buffer to be written.
is_lastSet to true for the last chunk. The callback will not be invoked again after it was invoked once with is_last set to true.

Definition at line 600 of file dart_tools_api.h.

◆ Dart_ServiceRequestCallback

typedef bool(* Dart_ServiceRequestCallback) (const char *method, const char **param_keys, const char **param_values, intptr_t num_params, void *user_data, const char **json_object)

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.

The return value of the callback indicates whether the response should be used as a regular result or an error result. Specifically, if the callback returns true, a regular JSON-RPC response is built in the following way:

{ "jsonrpc": "2.0", "result": <json_object>, "id": <some sequence id>, }

If the callback returns false, a JSON-RPC error is built like this:

{ "jsonrpc": "2.0", "error": <json_object>, "id": <some sequence id>, }

Parameters
methodThe rpc method name.
param_keysService requests can have key-value pair parameters. The keys and values are flattened and stored in arrays.
param_valuesThe values associated with the keys.
num_paramsThe length of the param_keys and param_values arrays.
user_dataThe user_data pointer registered with this handler.
resultA C string containing a valid JSON object. The returned pointer will be freed by the VM by calling free.
Returns
True if the result is a regular JSON-RPC response, false if the result is a JSON-RPC error.

Definition at line 82 of file dart_tools_api.h.

◆ Dart_ServiceStreamCancelCallback

typedef void(* Dart_ServiceStreamCancelCallback) (const char *stream_id)

A callback invoked when the VM service gets a request to cancel some stream.

Definition at line 207 of file dart_tools_api.h.

◆ Dart_ServiceStreamListenCallback

typedef bool(* Dart_ServiceStreamListenCallback) (const char *stream_id)

A callback invoked when the VM service gets a request to listen to some stream.

Returns
Returns true iff the embedder supports the named stream id.

Definition at line 201 of file dart_tools_api.h.

◆ Dart_TimelineRecorderCallback

typedef void(* Dart_TimelineRecorderCallback) (Dart_TimelineRecorderEvent *event)

Callback provided by the embedder to handle the completion of timeline events.

Parameters
eventA timeline event that has just been completed. The VM keeps ownership of the event and any field in it (i.e., the embedder should copy any values it needs after the callback returns).

Definition at line 482 of file dart_tools_api.h.

Enumeration Type Documentation

◆ Dart_Timeline_Event_Type

Enumerator
Dart_Timeline_Event_Begin 
Dart_Timeline_Event_End 
Dart_Timeline_Event_Instant 
Dart_Timeline_Event_Duration 
Dart_Timeline_Event_Async_Begin 
Dart_Timeline_Event_Async_End 
Dart_Timeline_Event_Async_Instant 
Dart_Timeline_Event_Counter 
Dart_Timeline_Event_Flow_Begin 
Dart_Timeline_Event_Flow_Step 
Dart_Timeline_Event_Flow_End 

Definition at line 342 of file dart_tools_api.h.

342 {
343 Dart_Timeline_Event_Begin, // Phase = 'B'.
344 Dart_Timeline_Event_End, // Phase = 'E'.
345 Dart_Timeline_Event_Instant, // Phase = 'i'.
346 Dart_Timeline_Event_Duration, // Phase = 'X'.
347 Dart_Timeline_Event_Async_Begin, // Phase = 'b'.
348 Dart_Timeline_Event_Async_End, // Phase = 'e'.
349 Dart_Timeline_Event_Async_Instant, // Phase = 'n'.
350 Dart_Timeline_Event_Counter, // Phase = 'C'.
351 Dart_Timeline_Event_Flow_Begin, // Phase = 's'.
352 Dart_Timeline_Event_Flow_Step, // Phase = 't'.
353 Dart_Timeline_Event_Flow_End, // Phase = 'f'.
Dart_Timeline_Event_Type
@ Dart_Timeline_Event_Async_Begin
@ Dart_Timeline_Event_Async_End
@ Dart_Timeline_Event_Begin
@ Dart_Timeline_Event_Counter
@ Dart_Timeline_Event_Flow_End
@ Dart_Timeline_Event_Duration
@ Dart_Timeline_Event_Flow_Begin
@ Dart_Timeline_Event_End
@ Dart_Timeline_Event_Instant
@ Dart_Timeline_Event_Async_Instant
@ Dart_Timeline_Event_Flow_Step

Function Documentation

◆ Dart_GetCurrentUserTag()

DART_EXPORT Dart_Handle Dart_GetCurrentUserTag ( )

◆ Dart_GetDefaultUserTag()

DART_EXPORT Dart_Handle Dart_GetDefaultUserTag ( )

◆ Dart_GetUserTagLabel()

DART_EXPORT DART_WARN_UNUSED_RESULT char * Dart_GetUserTagLabel ( Dart_Handle  user_tag)

◆ Dart_InvokeVMServiceMethod()

DART_EXPORT bool Dart_InvokeVMServiceMethod ( uint8_t *  request_json,
intptr_t  request_json_length,
uint8_t **  response_json,
intptr_t *  response_json_length,
char **  error 
)

Invoke a vm-service method and wait for its result.

Parameters
request_jsonThe utf8-encoded json-rpc request.
request_json_lengthThe length of the json-rpc request.
response_jsonThe returned utf8-encoded json response, must be free()ed by caller.
response_json_lengthThe length of the returned json response.
errorAn optional error, must be free()ed by caller.
Returns
Whether the call was successfully performed.

NOTE: This method does not need a current isolate and must not have the vm-isolate being the current isolate. It must be called after Dart_Initialize() and before Dart_Cleanup().

◆ Dart_IsolateGroupHeapNewCapacityMetric()

DART_EXPORT int64_t Dart_IsolateGroupHeapNewCapacityMetric ( Dart_IsolateGroup  group)

◆ Dart_IsolateGroupHeapNewExternalMetric()

DART_EXPORT int64_t Dart_IsolateGroupHeapNewExternalMetric ( Dart_IsolateGroup  group)

◆ Dart_IsolateGroupHeapNewUsedMetric()

DART_EXPORT int64_t Dart_IsolateGroupHeapNewUsedMetric ( Dart_IsolateGroup  group)

◆ Dart_IsolateGroupHeapOldCapacityMetric()

DART_EXPORT int64_t Dart_IsolateGroupHeapOldCapacityMetric ( Dart_IsolateGroup  group)

◆ Dart_IsolateGroupHeapOldExternalMetric()

DART_EXPORT int64_t Dart_IsolateGroupHeapOldExternalMetric ( Dart_IsolateGroup  group)

◆ Dart_IsolateGroupHeapOldUsedMetric()

DART_EXPORT int64_t Dart_IsolateGroupHeapOldUsedMetric ( Dart_IsolateGroup  group)

Return metrics gathered for the VM and individual isolates.

◆ Dart_IsReloading()

DART_EXPORT bool Dart_IsReloading ( )

Returns true if isolate is currently reloading.

◆ Dart_NewUserTag()

DART_EXPORT Dart_Handle Dart_NewUserTag ( const char *  label)

◆ Dart_RecordTimelineEvent()

DART_EXPORT void Dart_RecordTimelineEvent ( const char *  label,
int64_t  timestamp0,
int64_t  timestamp1_or_id,
intptr_t  flow_id_count,
const int64_t *  flow_ids,
Dart_Timeline_Event_Type  type,
intptr_t  argument_count,
const char **  argument_names,
const char **  argument_values 
)

Add a timeline event to the embedder stream.

Note regarding flow events: events must be associated with flow IDs in two different ways to allow flow events to be serialized correctly in both Chrome's JSON trace event format and Perfetto's proto trace format. Events of type |Dart_Timeline_Event_Flow_Begin|, |Dart_Timeline_Event_Flow_Step|, and |Dart_Timeline_Event_Flow_End| must be reported to support serialization in Chrome's trace format. The |flow_ids| argument must be supplied when reporting events of type |Dart_Timeline_Event_Begin|, |Dart_Timeline_Event_Duration|, |Dart_Timeline_Event_Instant|, |Dart_Timeline_Event_Async_Begin|, and |Dart_Timeline_Event_Async_Instant| to support serialization in Perfetto's proto format.

The Dart VM can use various underlying recorders depending on configuration and operating system. Many recorders do not support all event types; unsupported event types are siliently dropped. Some recorders do not accept timestamps as input, instead implicitly using the time the event is recorded. For maximum compatibility, record events with the Begin and End types as they occur instead of using the Duration type or buffering.

Parameters
labelThe name of the event. Its lifetime must extend at least until Dart_Cleanup.
timestamp0The first timestamp of the event.
timestamp1_or_idWhen reporting an event of type |Dart_Timeline_Event_Duration|, the second (end) timestamp of the event should be passed through |timestamp1_or_id|. When reporting an event of type |Dart_Timeline_Event_Async_Begin|, |Dart_Timeline_Event_Async_End|, or |Dart_Timeline_Event_Async_Instant|, the async ID associated with the event should be passed through |timestamp1_or_id|. When reporting an event of type |Dart_Timeline_Event_Flow_Begin|, |Dart_Timeline_Event_Flow_Step|, or |Dart_Timeline_Event_Flow_End|, the flow ID associated with the event should be passed through |timestamp1_or_id|. When reporting an event of type |Dart_Timeline_Event_Begin| or |Dart_Timeline_Event_End|, the event ID associated with the event should be passed through |timestamp1_or_id|. Note that this event ID will only be used by the MacOS recorder. The argument to |timestamp1_or_id| will not be used when reporting events of other types.
flow_id_countThe number of flow IDs associated with this event.
flow_idsAn array of flow IDs associated with this event. The array may be reclaimed when this call returns.
argument_countThe number of argument names and values.
argument_namesAn array of names of the arguments. The lifetime of the names must extend at least until Dart_Cleanup. The array may be reclaimed when this call returns.
argument_valuesAn array of values of the arguments. The values and the array may be reclaimed when this call returns.

◆ Dart_RegisterIsolateServiceRequestCallback()

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 on a specific isolate. The callback will be invoked with the current isolate set to the request target.

Parameters
methodThe name of the method that this callback is responsible for.
callbackThe callback to invoke.
user_dataThe 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_RegisterRootServiceRequestCallback()

DART_EXPORT void Dart_RegisterRootServiceRequestCallback ( 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.

Parameters
methodThe name of the command that this callback is responsible for.
callbackThe callback to invoke.
user_dataThe 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_ServiceSendDataEvent()

DART_EXPORT char * Dart_ServiceSendDataEvent ( const char *  stream_id,
const char *  event_kind,
const uint8_t *  bytes,
intptr_t  bytes_length 
)

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.

Parameters
stream_idThe id of the stream on which to post the event.
event_kindA string identifying what kind of event this is. For example, 'WriteEvent'.
bytesA pointer to an array of bytes.
bytes_lengthThe length of the byte array.
Returns
NULL if the arguments are well formed. Otherwise, returns an error string. The caller is responsible for freeing the error message.

◆ Dart_SetCurrentUserTag()

DART_EXPORT Dart_Handle Dart_SetCurrentUserTag ( Dart_Handle  user_tag)

◆ Dart_SetEmbedderInformationCallback()

DART_EXPORT void Dart_SetEmbedderInformationCallback ( Dart_EmbedderInformationCallback  callback)

Register a Dart_ServiceRequestCallback to be called to handle requests for the named rpc. The callback will be invoked without a current isolate.

Parameters
methodThe name of the command that this callback is responsible for.
callbackThe callback to invoke.
user_dataThe user data passed to the callback.

NOTE: If multiple callbacks are registered, only the last callback registered will be remembered.

◆ Dart_SetEnabledTimelineCategory()

DART_EXPORT bool Dart_SetEnabledTimelineCategory ( const char *  categories)

Enable tracking of specified timeline category. This is operational only when systrace timeline functionality is turned on.

Parameters
categoriesA comma separated list of categories that need to be enabled, the categories are "all" : All categories "API" - Execution of Dart C API functions "Compiler" - Execution of Dart JIT compiler "CompilerVerbose" - More detailed Execution of Dart JIT compiler "Dart" - Execution of Dart code "Debugger" - Execution of Dart debugger "Embedder" - Execution of Dart embedder code "GC" - Execution of Dart Garbage Collector "Isolate" - Dart Isolate lifecycle execution "VM" - Execution in Dart VM runtime code "" - None

When "all" is specified all the categories are enabled. When a comma separated list of categories is specified, the categories that are specified will be enabled and the rest will be disabled. When "" is specified all the categories are disabled. The category names are case sensitive. eg: Dart_EnableTimelineCategory("all"); Dart_EnableTimelineCategory("GC,API,Isolate"); Dart_EnableTimelineCategory("GC,Debugger,Dart");

Returns
True if the categories were successfully enabled, False otherwise.

◆ Dart_SetFileModifiedCallback()

DART_EXPORT char * Dart_SetFileModifiedCallback ( Dart_FileModifiedCallback  file_modified_callback)

◆ Dart_SetServiceStreamCallbacks()

DART_EXPORT char * Dart_SetServiceStreamCallbacks ( Dart_ServiceStreamListenCallback  listen_callback,
Dart_ServiceStreamCancelCallback  cancel_callback 
)

Adds VM service stream callbacks.

Parameters
listen_callbackA 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.
cancel_callbackA 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.
Returns
Success if the callbacks were added. Otherwise, returns an error handle.

◆ Dart_SetThreadName()

DART_EXPORT void Dart_SetThreadName ( const char *  name)

Associates a name with the current thread. This name will be used to name threads in the timeline. Can only be called after a call to Dart_Initialize.

Parameters
nameThe name of the thread.

◆ Dart_SetTimelineRecorderCallback()

DART_EXPORT void Dart_SetTimelineRecorderCallback ( Dart_TimelineRecorderCallback  callback)

Register a Dart_TimelineRecorderCallback to be called as timeline events are completed.

The callback will be invoked without a current isolate.

The callback will be invoked on the thread completing the event. Because Dart_RecordTimelineEvent may be called by any thread, the callback may be called on any thread.

The callback may be invoked at any time after Dart_Initialize is called and before Dart_Cleanup returns.

If multiple callbacks are registered, only the last callback registered will be remembered. Providing a NULL callback will clear the registration (i.e., a NULL callback produced a no-op instead of a crash).

Setting a callback is insufficient to receive events through the callback. The VM flag timeline_recorder must also be set to callback.

◆ Dart_TimelineGetMicros()

DART_EXPORT int64_t Dart_TimelineGetMicros ( )

Returns a timestamp in microseconds. This timestamp is suitable for passing into the timeline system, and uses the same monotonic clock as dart:developer's Timeline.now.

Returns
A timestamp that can be passed to the timeline system.

◆ Dart_TimelineGetTicks()

DART_EXPORT int64_t Dart_TimelineGetTicks ( )

Returns a raw timestamp in from the monotonic clock.

Returns
A raw timestamp from the monotonic clock.

◆ Dart_TimelineGetTicksFrequency()

DART_EXPORT int64_t Dart_TimelineGetTicksFrequency ( )

Returns the frequency of the monotonic clock.

Returns
The frequency of the monotonic clock.

◆ Dart_WriteHeapSnapshot()

DART_EXPORT char * Dart_WriteHeapSnapshot ( Dart_HeapSnapshotWriteChunkCallback  write,
void *  context 
)

Generate heap snapshot of the current isolate group and stream it into the given callback. VM would produce snapshot in chunks and send these chunks one by one back to the embedder by invoking the provided callback.

This API enables embedder to stream snapshot into a file or socket without allocating a buffer to hold the whole snapshot in memory.

The isolate group will be paused for the duration of this operation.

Parameters
writeCallback used to write chunks of the heap snapshot.
contextOpaque context which would be passed on each invocation of write callback.
Returns
nullptr if the operation is successful otherwise error message. Caller owns error message string and needs to free it.