123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658 |
- // 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 RUNTIME_INCLUDE_DART_TOOLS_API_H_
- #define RUNTIME_INCLUDE_DART_TOOLS_API_H_
- #include "dart_api.h" /* NOLINT */
- /** \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
- * ========
- */
- /**
- * ILLEGAL_ISOLATE_ID is a number guaranteed never to be associated with a
- * valid isolate.
- */
- #define ILLEGAL_ISOLATE_ID ILLEGAL_PORT
- /**
- * ILLEGAL_ISOLATE_GROUP_ID is a number guaranteed never to be associated with a
- * valid isolate group.
- */
- #define ILLEGAL_ISOLATE_GROUP_ID 0
- /*
- * =======
- * 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.
- *
- * 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>,
- * }
- *
- * \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.
- * \param result A C string containing a valid JSON object. The returned
- * pointer will be freed by the VM by calling free.
- *
- * \return True if the result is a regular JSON-RPC response, false if the
- * result is a JSON-RPC error.
- */
- 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);
- /**
- * 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);
- /**
- * 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.
- */
- #define DART_EMBEDDER_INFORMATION_CURRENT_VERSION (0x00000001)
- typedef struct {
- int32_t version;
- const char* name; // [optional] The name of the embedder
- int64_t current_rss; // [optional] the current RSS of the embedder
- int64_t max_rss; // [optional] the maximum RSS of the embedder
- } Dart_EmbedderInformation;
- /**
- * Callback provided by the embedder that is used by the VM to request
- * information.
- *
- * \return 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.
- */
- typedef void (*Dart_EmbedderInformationCallback)(
- Dart_EmbedderInformation* info);
- /**
- * 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 are registered, only the last callback registered
- * will be remembered.
- */
- DART_EXPORT void Dart_SetEmbedderInformationCallback(
- Dart_EmbedderInformationCallback callback);
- /**
- * Invoke a vm-service method and wait for its result.
- *
- * \param request_json The utf8-encoded json-rpc request.
- * \param request_json_length The length of the json-rpc request.
- *
- * \param response_json The returned utf8-encoded json response, must be
- * free()ed by caller.
- * \param response_json_length The length of the returned json response.
- * \param error An optional error, must be free()ed by caller.
- *
- * \return 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_EXPORT bool Dart_InvokeVMServiceMethod(uint8_t* request_json,
- intptr_t request_json_length,
- uint8_t** response_json,
- intptr_t* response_json_length,
- char** error);
- /*
- * ========
- * 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 char* 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 NULL if the arguments are well formed. Otherwise, returns an
- * error string. The caller is responsible for freeing the error message.
- */
- DART_EXPORT char* Dart_ServiceSendDataEvent(const char* stream_id,
- const char* event_kind,
- const uint8_t* bytes,
- intptr_t bytes_length);
- /*
- * ========
- * Reload support
- * ========
- *
- * These functions are used to implement reloading in the Dart VM.
- * This is an experimental feature, so embedders should be prepared
- * for these functions to change.
- */
- /**
- * 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.
- */
- typedef bool (*Dart_FileModifiedCallback)(const char* url, int64_t since);
- DART_EXPORT char* Dart_SetFileModifiedCallback(
- Dart_FileModifiedCallback file_modified_callback);
- /**
- * Returns true if isolate is currently reloading.
- */
- DART_EXPORT bool Dart_IsReloading();
- /*
- * ========
- * Timeline
- * ========
- */
- /**
- * Enable tracking of specified timeline category. This is operational
- * only when systrace timeline functionality is turned on.
- *
- * \param categories A 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");
- *
- * \return True if the categories were successfully enabled, False otherwise.
- */
- DART_EXPORT bool Dart_SetEnabledTimelineCategory(const char* categories);
- /**
- * 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.
- *
- * \return A timestamp that can be passed to the timeline system.
- */
- DART_EXPORT int64_t Dart_TimelineGetMicros();
- /**
- * Returns a raw timestamp in from the monotonic clock.
- *
- * \return A raw timestamp from the monotonic clock.
- */
- DART_EXPORT int64_t Dart_TimelineGetTicks();
- /**
- * Returns the frequency of the monotonic clock.
- *
- * \return The frequency of the monotonic clock.
- */
- DART_EXPORT int64_t Dart_TimelineGetTicksFrequency();
- typedef enum {
- Dart_Timeline_Event_Begin, // Phase = 'B'.
- Dart_Timeline_Event_End, // Phase = 'E'.
- Dart_Timeline_Event_Instant, // Phase = 'i'.
- Dart_Timeline_Event_Duration, // Phase = 'X'.
- Dart_Timeline_Event_Async_Begin, // Phase = 'b'.
- Dart_Timeline_Event_Async_End, // Phase = 'e'.
- Dart_Timeline_Event_Async_Instant, // Phase = 'n'.
- Dart_Timeline_Event_Counter, // Phase = 'C'.
- Dart_Timeline_Event_Flow_Begin, // Phase = 's'.
- Dart_Timeline_Event_Flow_Step, // Phase = 't'.
- Dart_Timeline_Event_Flow_End, // Phase = 'f'.
- } Dart_Timeline_Event_Type;
- /**
- * Add a timeline event to the embedder stream.
- *
- * DEPRECATED: this function will be removed in Dart SDK v3.2.
- *
- * \param label The name of the event. Its lifetime must extend at least until
- * Dart_Cleanup.
- * \param timestamp0 The first timestamp of the event.
- * \param timestamp1_or_id When 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.
- * \param argument_count The number of argument names and values.
- * \param argument_names An 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.
- * \param argument_values An array of values of the arguments. The values and
- * the array may be reclaimed when this call returns.
- */
- DART_EXPORT void Dart_TimelineEvent(const char* label,
- int64_t timestamp0,
- int64_t timestamp1_or_id,
- 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.
- *
- * \param label The name of the event. Its lifetime must extend at least until
- * Dart_Cleanup.
- * \param timestamp0 The first timestamp of the event.
- * \param timestamp1_or_id When 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.
- * \param flow_id_count The number of flow IDs associated with this event.
- * \param flow_ids An array of flow IDs associated with this event. The array
- * may be reclaimed when this call returns.
- * \param argument_count The number of argument names and values.
- * \param argument_names An 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.
- * \param argument_values An array of values of the arguments. The values and
- * the array may be reclaimed when this call returns.
- */
- 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);
- /**
- * 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.
- *
- * \param name The name of the thread.
- */
- DART_EXPORT void Dart_SetThreadName(const char* name);
- typedef struct {
- const char* name;
- const char* value;
- } Dart_TimelineRecorderEvent_Argument;
- #define DART_TIMELINE_RECORDER_CURRENT_VERSION (0x00000002)
- typedef struct {
- /* Set to DART_TIMELINE_RECORDER_CURRENT_VERSION */
- int32_t version;
- /* The event's type / phase. */
- Dart_Timeline_Event_Type type;
- /* The event's timestamp according to the same clock as
- * Dart_TimelineGetMicros. For a duration event, this is the beginning time.
- */
- int64_t timestamp0;
- /**
- * For a duration event, this is the end time. For an async event, this is the
- * async ID. For a flow event, this is the flow ID. For a begin or end event,
- * this is the event ID (which is only referenced by the MacOS recorder).
- */
- int64_t timestamp1_or_id;
- /* The current isolate of the event, as if by Dart_GetMainPortId, or
- * ILLEGAL_PORT if the event had no current isolate. */
- Dart_Port isolate;
- /* The current isolate group of the event, as if by
- * Dart_CurrentIsolateGroupId, or ILLEGAL_PORT if the event had no current
- * isolate group. */
- Dart_IsolateGroupId isolate_group;
- /* The callback data associated with the isolate if any. */
- void* isolate_data;
- /* The callback data associated with the isolate group if any. */
- void* isolate_group_data;
- /* The name / label of the event. */
- const char* label;
- /* The stream / category of the event. */
- const char* stream;
- intptr_t argument_count;
- Dart_TimelineRecorderEvent_Argument* arguments;
- } Dart_TimelineRecorderEvent;
- /**
- * Callback provided by the embedder to handle the completion of timeline
- * events.
- *
- * \param event A 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).
- */
- typedef void (*Dart_TimelineRecorderCallback)(
- Dart_TimelineRecorderEvent* event);
- /**
- * 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_TimelineEvent` 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_EXPORT void Dart_SetTimelineRecorderCallback(
- Dart_TimelineRecorderCallback callback);
- /*
- * =======
- * Metrics
- * =======
- */
- /**
- * Return metrics gathered for the VM and individual isolates.
- */
- DART_EXPORT int64_t
- Dart_IsolateGroupHeapOldUsedMetric(Dart_IsolateGroup group); // Byte
- DART_EXPORT int64_t
- Dart_IsolateGroupHeapOldCapacityMetric(Dart_IsolateGroup group); // Byte
- DART_EXPORT int64_t
- Dart_IsolateGroupHeapOldExternalMetric(Dart_IsolateGroup group); // Byte
- DART_EXPORT int64_t
- Dart_IsolateGroupHeapNewUsedMetric(Dart_IsolateGroup group); // Byte
- DART_EXPORT int64_t
- Dart_IsolateGroupHeapNewCapacityMetric(Dart_IsolateGroup group); // Byte
- DART_EXPORT int64_t
- Dart_IsolateGroupHeapNewExternalMetric(Dart_IsolateGroup group); // Byte
- /*
- * ========
- * UserTags
- * ========
- */
- /*
- * Gets the current isolate's currently set UserTag instance.
- *
- * \return The currently set UserTag instance.
- */
- DART_EXPORT Dart_Handle Dart_GetCurrentUserTag();
- /*
- * Gets the current isolate's default UserTag instance.
- *
- * \return The default UserTag with label 'Default'
- */
- DART_EXPORT Dart_Handle Dart_GetDefaultUserTag();
- /*
- * Creates a new UserTag instance.
- *
- * \param label The name of the new UserTag.
- *
- * \return The newly created UserTag instance or an error handle.
- */
- DART_EXPORT Dart_Handle Dart_NewUserTag(const char* label);
- /*
- * Updates the current isolate's UserTag to a new value.
- *
- * \param user_tag The UserTag to be set as the current UserTag.
- *
- * \return The previously set UserTag instance or an error handle.
- */
- DART_EXPORT Dart_Handle Dart_SetCurrentUserTag(Dart_Handle user_tag);
- /*
- * Returns the label of a given UserTag instance.
- *
- * \param user_tag The UserTag from which the label will be retrieved.
- *
- * \return The UserTag's label. NULL if the user_tag is invalid. The caller is
- * responsible for freeing the returned label.
- */
- DART_EXPORT DART_WARN_UNUSED_RESULT char* Dart_GetUserTagLabel(
- Dart_Handle user_tag);
- /*
- * =======
- * Heap Snapshot
- * =======
- */
- /**
- * Callback provided by the caller of `Dart_WriteHeapSnapshot` which is
- * used to write out chunks of the requested heap snapshot.
- *
- * \param context An opaque context which was passed to `Dart_WriteHeapSnapshot`
- * together with this callback.
- *
- * \param buffer Pointer to the buffer containing a chunk of the snapshot.
- * The callback owns the buffer and needs to `free` it.
- *
- * \param size Number of bytes in the `buffer` to be written.
- *
- * \param is_last Set to `true` for the last chunk. The callback will not
- * be invoked again after it was invoked once with `is_last` set to `true`.
- */
- typedef void (*Dart_HeapSnapshotWriteChunkCallback)(void* context,
- uint8_t* buffer,
- intptr_t size,
- bool is_last);
- /**
- * 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.
- *
- * \param write Callback used to write chunks of the heap snapshot.
- *
- * \param context Opaque 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.
- */
- DART_EXPORT char* Dart_WriteHeapSnapshot(
- Dart_HeapSnapshotWriteChunkCallback write,
- void* context);
- #endif // RUNTIME_INCLUDE_DART_TOOLS_API_H_
|