1// Copyright (c) 2011, the Dart project authors. Please see the AUTHORS file
2// for details. All rights reserved. Use of this source code is governed by a
3// BSD-style license that can be found in the LICENSE file.
4
5#ifndef RUNTIME_INCLUDE_DART_TOOLS_API_H_
6#define RUNTIME_INCLUDE_DART_TOOLS_API_H_
7
8#include "dart_api.h"
9
10/** \mainpage Dart Tools Embedding API Reference
11 *
12 * This reference describes the Dart embedding API for tools. Tools include
13 * a debugger, service protocol, and timeline.
14 *
15 * NOTE: The APIs described in this file are unstable and subject to change.
16 *
17 * This reference is generated from the header include/dart_tools_api.h.
18 */
19
20/*
21 * ========
22 * Debugger
23 * ========
24 */
25
26/**
27 * ILLEGAL_ISOLATE_ID is a number guaranteed never to be associated with a
28 * valid isolate.
29 */
30#define ILLEGAL_ISOLATE_ID ILLEGAL_PORT
31
32
33/*
34 * =======
35 * Service
36 * =======
37 */
38
39/**
40 * A service request callback function.
41 *
42 * These callbacks, registered by the embedder, are called when the VM receives
43 * a service request it can't handle and the service request command name
44 * matches one of the embedder registered handlers.
45 *
46 * The return value of the callback indicates whether the response
47 * should be used as a regular result or an error result.
48 * Specifically, if the callback returns true, a regular JSON-RPC
49 * response is built in the following way:
50 *
51 * {
52 * "jsonrpc": "2.0",
53 * "result": <json_object>,
54 * "id": <some sequence id>,
55 * }
56 *
57 * If the callback returns false, a JSON-RPC error is built like this:
58 *
59 * {
60 * "jsonrpc": "2.0",
61 * "error": <json_object>,
62 * "id": <some sequence id>,
63 * }
64 *
65 * \param method The rpc method name.
66 * \param param_keys Service requests can have key-value pair parameters. The
67 * keys and values are flattened and stored in arrays.
68 * \param param_values The values associated with the keys.
69 * \param num_params The length of the param_keys and param_values arrays.
70 * \param user_data The user_data pointer registered with this handler.
71 * \param result A C string containing a valid JSON object. The returned
72 * pointer will be freed by the VM by calling free.
73 *
74 * \return True if the result is a regular JSON-RPC response, false if the
75 * result is a JSON-RPC error.
76 */
77typedef bool (*Dart_ServiceRequestCallback)(const char* method,
78 const char** param_keys,
79 const char** param_values,
80 intptr_t num_params,
81 void* user_data,
82 const char** json_object);
83
84/**
85 * Register a Dart_ServiceRequestCallback to be called to handle
86 * requests for the named rpc on a specific isolate. The callback will
87 * be invoked with the current isolate set to the request target.
88 *
89 * \param method The name of the method that this callback is responsible for.
90 * \param callback The callback to invoke.
91 * \param user_data The user data passed to the callback.
92 *
93 * NOTE: If multiple callbacks with the same name are registered, only
94 * the last callback registered will be remembered.
95 */
96DART_EXPORT void Dart_RegisterIsolateServiceRequestCallback(
97 const char* method,
98 Dart_ServiceRequestCallback callback,
99 void* user_data);
100
101/**
102 * Register a Dart_ServiceRequestCallback to be called to handle
103 * requests for the named rpc. The callback will be invoked without a
104 * current isolate.
105 *
106 * \param method The name of the command that this callback is responsible for.
107 * \param callback The callback to invoke.
108 * \param user_data The user data passed to the callback.
109 *
110 * NOTE: If multiple callbacks with the same name are registered, only
111 * the last callback registered will be remembered.
112 */
113DART_EXPORT void Dart_RegisterRootServiceRequestCallback(
114 const char* method,
115 Dart_ServiceRequestCallback callback,
116 void* user_data);
117
118/**
119 * Embedder information which can be requested by the VM for internal or
120 * reporting purposes.
121 *
122 * The pointers in this structure are not going to be cached or freed by the VM.
123 */
124
125 #define DART_EMBEDDER_INFORMATION_CURRENT_VERSION (0x00000001)
126
127typedef struct {
128 int32_t version;
129 const char* name; // [optional] The name of the embedder
130 int64_t current_rss; // [optional] the current RSS of the embedder
131 int64_t max_rss; // [optional] the maximum RSS of the embedder
132} Dart_EmbedderInformation;
133
134/**
135 * Callback provided by the embedder that is used by the vm to request
136 * information.
137 *
138 * \return Returns a pointer to a Dart_EmbedderInformation structure.
139 * The embedder keeps the ownership of the structure and any field in it.
140 * The embedder must ensure that the structure will remain valid until the
141 * next invokation of the callback.
142 */
143typedef void (*Dart_EmbedderInformationCallback)(
144 Dart_EmbedderInformation* info);
145
146/**
147 * Register a Dart_ServiceRequestCallback to be called to handle
148 * requests for the named rpc. The callback will be invoked without a
149 * current isolate.
150 *
151 * \param method The name of the command that this callback is responsible for.
152 * \param callback The callback to invoke.
153 * \param user_data The user data passed to the callback.
154 *
155 * NOTE: If multiple callbacks with the same name are registered, only
156 * the last callback registered will be remembered.
157 */
158DART_EXPORT void Dart_SetEmbedderInformationCallback(
159 Dart_EmbedderInformationCallback callback);
160
161/**
162 * Invoke a vm-service method and wait for its result.
163 *
164 * \param request_json The utf8-encoded json-rpc request.
165 * \param request_json_length The length of the json-rpc request.
166 *
167 * \param response_json The returned utf8-encoded json response, must be
168 * free()ed by caller.
169 * \param response_json_length The length of the returned json response.
170 * \param error An optional error, must be free()ed by caller.
171 *
172 * \return Whether the call was sucessfully performed.
173 *
174 * NOTE: This method does not need a current isolate and must not have the
175 * vm-isolate being the current isolate. It must be called after
176 * Dart_Initialize() and before Dart_Cleanup().
177 */
178DART_EXPORT bool Dart_InvokeVMServiceMethod(uint8_t* request_json,
179 intptr_t request_json_length,
180 uint8_t** response_json,
181 intptr_t* response_json_length,
182 char** error);
183
184/*
185 * ========
186 * Event Streams
187 * ========
188 */
189
190/**
191 * A callback invoked when the VM service gets a request to listen to
192 * some stream.
193 *
194 * \return Returns true iff the embedder supports the named stream id.
195 */
196typedef bool (*Dart_ServiceStreamListenCallback)(const char* stream_id);
197
198/**
199 * A callback invoked when the VM service gets a request to cancel
200 * some stream.
201 */
202typedef void (*Dart_ServiceStreamCancelCallback)(const char* stream_id);
203
204/**
205 * Adds VM service stream callbacks.
206 *
207 * \param listen_callback A function pointer to a listen callback function.
208 * A listen callback function should not be already set when this function
209 * is called. A NULL value removes the existing listen callback function
210 * if any.
211 *
212 * \param cancel_callback A function pointer to a cancel callback function.
213 * A cancel callback function should not be already set when this function
214 * is called. A NULL value removes the existing cancel callback function
215 * if any.
216 *
217 * \return Success if the callbacks were added. Otherwise, returns an
218 * error handle.
219 */
220DART_EXPORT char* Dart_SetServiceStreamCallbacks(
221 Dart_ServiceStreamListenCallback listen_callback,
222 Dart_ServiceStreamCancelCallback cancel_callback);
223
224/**
225 * A callback invoked when the VM service receives an event.
226 */
227typedef void (*Dart_NativeStreamConsumer)(const uint8_t* event_json,
228 intptr_t event_json_length);
229
230/**
231 * Sets the native VM service stream callbacks for a particular stream.
232 * Note: The function may be called on multiple threads concurrently.
233 *
234 * \param consumer A function pointer to an event handler callback function.
235 * A NULL value removes the existing listen callback function if any.
236 *
237 * \param stream_id The ID of the stream on which to set the callback.
238 */
239DART_EXPORT void Dart_SetNativeServiceStreamCallback(
240 Dart_NativeStreamConsumer consumer,
241 const char* stream_id);
242
243/**
244 * Sends a data event to clients of the VM Service.
245 *
246 * A data event is used to pass an array of bytes to subscribed VM
247 * Service clients. For example, in the standalone embedder, this is
248 * function used to provide WriteEvents on the Stdout and Stderr
249 * streams.
250 *
251 * If the embedder passes in a stream id for which no client is
252 * subscribed, then the event is ignored.
253 *
254 * \param stream_id The id of the stream on which to post the event.
255 *
256 * \param event_kind A string identifying what kind of event this is.
257 * For example, 'WriteEvent'.
258 *
259 * \param bytes A pointer to an array of bytes.
260 *
261 * \param bytes_length The length of the byte array.
262 *
263 * \return Success if the arguments are well formed. Otherwise, returns an
264 * error handle.
265 */
266DART_EXPORT Dart_Handle Dart_ServiceSendDataEvent(const char* stream_id,
267 const char* event_kind,
268 const uint8_t* bytes,
269 intptr_t bytes_length);
270
271/*
272 * ========
273 * Reload support
274 * ========
275 *
276 * These functions are used to implement reloading in the Dart VM.
277 * This is an experimental feature, so embedders should be prepared
278 * for these functions to change.
279 */
280
281/**
282 * A callback which determines whether the file at some url has been
283 * modified since some time. If the file cannot be found, true should
284 * be returned.
285 */
286typedef bool (*Dart_FileModifiedCallback)(const char* url, int64_t since);
287
288DART_EXPORT char* Dart_SetFileModifiedCallback(
289 Dart_FileModifiedCallback file_modified_callback);
290
291/**
292 * Returns true if isolate is currently reloading.
293 */
294DART_EXPORT bool Dart_IsReloading();
295
296/*
297 * ========
298 * Timeline
299 * ========
300 */
301
302/**
303 * Returns a timestamp in microseconds. This timestamp is suitable for
304 * passing into the timeline system, and uses the same monotonic clock
305 * as dart:developer's Timeline.now.
306 *
307 * \return A timestamp that can be passed to the timeline system.
308 */
309DART_EXPORT int64_t Dart_TimelineGetMicros();
310
311/** Timeline stream for Dart API calls */
312#define DART_TIMELINE_STREAM_API (1 << 0)
313/** Timeline stream for compiler events */
314#define DART_TIMELINE_STREAM_COMPILER (1 << 1)
315/** Timeline stream for Dart provided events */
316#define DART_TIMELINE_STREAM_DART (1 << 2)
317/** Timeline stream for debugger provided events */
318#define DART_TIMELINE_STREAM_DEBUGGER (1 << 3)
319/** Timeline stream for embedder provided events */
320#define DART_TIMELINE_STREAM_EMBEDDER (1 << 4)
321/** Timeline stream for GC events */
322#define DART_TIMELINE_STREAM_GC (1 << 5)
323/** Timeline stream for isolate events */
324#define DART_TIMELINE_STREAM_ISOLATE (1 << 6)
325/** Timeline stream for VM events */
326#define DART_TIMELINE_STREAM_VM (1 << 7)
327
328/** All timeline streams */
329#define DART_TIMELINE_STREAM_ALL \
330 (DART_TIMELINE_STREAM_API | DART_TIMELINE_STREAM_COMPILER | \
331 DART_TIMELINE_STREAM_DART | DART_TIMELINE_STREAM_DEBUGGER | \
332 DART_TIMELINE_STREAM_EMBEDDER | DART_TIMELINE_STREAM_GC | \
333 DART_TIMELINE_STREAM_ISOLATE | DART_TIMELINE_STREAM_VM)
334
335/** Disable all timeline stream recording */
336#define DART_TIMELINE_STREAM_DISABLE 0
337
338/**
339 * Start recording timeline events for the entire VM (including all isolates).
340 *
341 * \param stream_mask A bitmask of streams that should be recorded.
342 *
343 * NOTE: Calling with 0 disables recording of all streams.
344 */
345DART_EXPORT void Dart_GlobalTimelineSetRecordedStreams(int64_t stream_mask);
346
347typedef enum {
348 Dart_Timeline_Event_Begin, // Phase = 'B'.
349 Dart_Timeline_Event_End, // Phase = 'E'.
350 Dart_Timeline_Event_Instant, // Phase = 'i'.
351 Dart_Timeline_Event_Duration, // Phase = 'X'.
352 Dart_Timeline_Event_Async_Begin, // Phase = 'b'.
353 Dart_Timeline_Event_Async_End, // Phase = 'e'.
354 Dart_Timeline_Event_Async_Instant, // Phase = 'n'.
355 Dart_Timeline_Event_Counter, // Phase = 'C'.
356 Dart_Timeline_Event_Flow_Begin, // Phase = 's'.
357 Dart_Timeline_Event_Flow_Step, // Phase = 't'.
358 Dart_Timeline_Event_Flow_End, // Phase = 'f'.
359} Dart_Timeline_Event_Type;
360
361/**
362 * Add a timeline event to the embedder stream.
363 *
364 * \param label The name of the event. Its lifetime must extend at least until
365 * Dart_Cleanup.
366 * \param timestamp0 The first timestamp of the event.
367 * \param timestamp1_or_async_id The second timestamp of the event or
368 * the async id.
369 * \param argument_count The number of argument names and values.
370 * \param argument_names An array of names of the arguments. The lifetime of the
371 * names must extend at least until Dart_Cleanup. The array may be reclaimed
372 * when this call returns.
373 * \param argument_values An array of values of the arguments. The values and
374 * the array may be reclaimed when this call returns.
375 */
376DART_EXPORT void Dart_TimelineEvent(const char* label,
377 int64_t timestamp0,
378 int64_t timestamp1_or_async_id,
379 Dart_Timeline_Event_Type type,
380 intptr_t argument_count,
381 const char** argument_names,
382 const char** argument_values);
383
384/**
385 * Associates a name with the current thread. This name will be used to name
386 * threads in the timeline. Can only be called after a call to Dart_Initialize.
387 *
388 * \param name The name of the thread.
389 */
390DART_EXPORT void Dart_SetThreadName(const char* name);
391
392/*
393 * =======
394 * Metrics
395 * =======
396 */
397
398/**
399 * Return metrics gathered for the VM and individual isolates.
400 *
401 * NOTE: Non-heap metrics are not available in PRODUCT builds of Dart.
402 * Calling the non-heap metric functions on a PRODUCT build might return invalid metrics.
403 */
404DART_EXPORT int64_t Dart_VMIsolateCountMetric(); // Counter
405DART_EXPORT int64_t Dart_VMCurrentRSSMetric(); // Byte
406DART_EXPORT int64_t Dart_VMPeakRSSMetric(); // Byte
407DART_EXPORT int64_t
408Dart_IsolateHeapOldUsedMetric(Dart_Isolate isolate); // Byte
409DART_EXPORT int64_t
410Dart_IsolateHeapOldUsedMaxMetric(Dart_Isolate isolate); // Byte
411DART_EXPORT int64_t
412Dart_IsolateHeapOldCapacityMetric(Dart_Isolate isolate); // Byte
413DART_EXPORT int64_t
414Dart_IsolateHeapOldCapacityMaxMetric(Dart_Isolate isolate); // Byte
415DART_EXPORT int64_t
416Dart_IsolateHeapOldExternalMetric(Dart_Isolate isolate); // Byte
417DART_EXPORT int64_t
418Dart_IsolateHeapNewUsedMetric(Dart_Isolate isolate); // Byte
419DART_EXPORT int64_t
420Dart_IsolateHeapNewUsedMaxMetric(Dart_Isolate isolate); // Byte
421DART_EXPORT int64_t
422Dart_IsolateHeapNewCapacityMetric(Dart_Isolate isolate); // Byte
423DART_EXPORT int64_t
424Dart_IsolateHeapNewCapacityMaxMetric(Dart_Isolate isolate); // Byte
425DART_EXPORT int64_t
426Dart_IsolateHeapNewExternalMetric(Dart_Isolate isolate); // Byte
427DART_EXPORT int64_t
428Dart_IsolateHeapGlobalUsedMetric(Dart_Isolate isolate); // Byte
429DART_EXPORT int64_t
430Dart_IsolateHeapGlobalUsedMaxMetric(Dart_Isolate isolate); // Byte
431DART_EXPORT int64_t
432Dart_IsolateRunnableLatencyMetric(Dart_Isolate isolate); // Microsecond
433DART_EXPORT int64_t
434Dart_IsolateRunnableHeapSizeMetric(Dart_Isolate isolate); // Byte
435
436#endif // RUNTIME_INCLUDE_DART_TOOLS_API_H_
437