dart_tools_api.h 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658
  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. #ifndef RUNTIME_INCLUDE_DART_TOOLS_API_H_
  5. #define RUNTIME_INCLUDE_DART_TOOLS_API_H_
  6. #include "dart_api.h" /* NOLINT */
  7. /** \mainpage Dart Tools Embedding API Reference
  8. *
  9. * This reference describes the Dart embedding API for tools. Tools include
  10. * a debugger, service protocol, and timeline.
  11. *
  12. * NOTE: The APIs described in this file are unstable and subject to change.
  13. *
  14. * This reference is generated from the header include/dart_tools_api.h.
  15. */
  16. /*
  17. * ========
  18. * Debugger
  19. * ========
  20. */
  21. /**
  22. * ILLEGAL_ISOLATE_ID is a number guaranteed never to be associated with a
  23. * valid isolate.
  24. */
  25. #define ILLEGAL_ISOLATE_ID ILLEGAL_PORT
  26. /**
  27. * ILLEGAL_ISOLATE_GROUP_ID is a number guaranteed never to be associated with a
  28. * valid isolate group.
  29. */
  30. #define ILLEGAL_ISOLATE_GROUP_ID 0
  31. /*
  32. * =======
  33. * Service
  34. * =======
  35. */
  36. /**
  37. * A service request callback function.
  38. *
  39. * These callbacks, registered by the embedder, are called when the VM receives
  40. * a service request it can't handle and the service request command name
  41. * matches one of the embedder registered handlers.
  42. *
  43. * The return value of the callback indicates whether the response
  44. * should be used as a regular result or an error result.
  45. * Specifically, if the callback returns true, a regular JSON-RPC
  46. * response is built in the following way:
  47. *
  48. * {
  49. * "jsonrpc": "2.0",
  50. * "result": <json_object>,
  51. * "id": <some sequence id>,
  52. * }
  53. *
  54. * If the callback returns false, a JSON-RPC error is built like this:
  55. *
  56. * {
  57. * "jsonrpc": "2.0",
  58. * "error": <json_object>,
  59. * "id": <some sequence id>,
  60. * }
  61. *
  62. * \param method The rpc method name.
  63. * \param param_keys Service requests can have key-value pair parameters. The
  64. * keys and values are flattened and stored in arrays.
  65. * \param param_values The values associated with the keys.
  66. * \param num_params The length of the param_keys and param_values arrays.
  67. * \param user_data The user_data pointer registered with this handler.
  68. * \param result A C string containing a valid JSON object. The returned
  69. * pointer will be freed by the VM by calling free.
  70. *
  71. * \return True if the result is a regular JSON-RPC response, false if the
  72. * result is a JSON-RPC error.
  73. */
  74. typedef bool (*Dart_ServiceRequestCallback)(const char* method,
  75. const char** param_keys,
  76. const char** param_values,
  77. intptr_t num_params,
  78. void* user_data,
  79. const char** json_object);
  80. /**
  81. * Register a Dart_ServiceRequestCallback to be called to handle
  82. * requests for the named rpc on a specific isolate. The callback will
  83. * be invoked with the current isolate set to the request target.
  84. *
  85. * \param method The name of the method that this callback is responsible for.
  86. * \param callback The callback to invoke.
  87. * \param user_data The user data passed to the callback.
  88. *
  89. * NOTE: If multiple callbacks with the same name are registered, only
  90. * the last callback registered will be remembered.
  91. */
  92. DART_EXPORT void Dart_RegisterIsolateServiceRequestCallback(
  93. const char* method,
  94. Dart_ServiceRequestCallback callback,
  95. void* user_data);
  96. /**
  97. * Register a Dart_ServiceRequestCallback to be called to handle
  98. * requests for the named rpc. The callback will be invoked without a
  99. * current isolate.
  100. *
  101. * \param method The name of the command that this callback is responsible for.
  102. * \param callback The callback to invoke.
  103. * \param user_data The user data passed to the callback.
  104. *
  105. * NOTE: If multiple callbacks with the same name are registered, only
  106. * the last callback registered will be remembered.
  107. */
  108. DART_EXPORT void Dart_RegisterRootServiceRequestCallback(
  109. const char* method,
  110. Dart_ServiceRequestCallback callback,
  111. void* user_data);
  112. /**
  113. * Embedder information which can be requested by the VM for internal or
  114. * reporting purposes.
  115. *
  116. * The pointers in this structure are not going to be cached or freed by the VM.
  117. */
  118. #define DART_EMBEDDER_INFORMATION_CURRENT_VERSION (0x00000001)
  119. typedef struct {
  120. int32_t version;
  121. const char* name; // [optional] The name of the embedder
  122. int64_t current_rss; // [optional] the current RSS of the embedder
  123. int64_t max_rss; // [optional] the maximum RSS of the embedder
  124. } Dart_EmbedderInformation;
  125. /**
  126. * Callback provided by the embedder that is used by the VM to request
  127. * information.
  128. *
  129. * \return Returns a pointer to a Dart_EmbedderInformation structure.
  130. * The embedder keeps the ownership of the structure and any field in it.
  131. * The embedder must ensure that the structure will remain valid until the
  132. * next invocation of the callback.
  133. */
  134. typedef void (*Dart_EmbedderInformationCallback)(
  135. Dart_EmbedderInformation* info);
  136. /**
  137. * Register a Dart_ServiceRequestCallback to be called to handle
  138. * requests for the named rpc. The callback will be invoked without a
  139. * current isolate.
  140. *
  141. * \param method The name of the command that this callback is responsible for.
  142. * \param callback The callback to invoke.
  143. * \param user_data The user data passed to the callback.
  144. *
  145. * NOTE: If multiple callbacks are registered, only the last callback registered
  146. * will be remembered.
  147. */
  148. DART_EXPORT void Dart_SetEmbedderInformationCallback(
  149. Dart_EmbedderInformationCallback callback);
  150. /**
  151. * Invoke a vm-service method and wait for its result.
  152. *
  153. * \param request_json The utf8-encoded json-rpc request.
  154. * \param request_json_length The length of the json-rpc request.
  155. *
  156. * \param response_json The returned utf8-encoded json response, must be
  157. * free()ed by caller.
  158. * \param response_json_length The length of the returned json response.
  159. * \param error An optional error, must be free()ed by caller.
  160. *
  161. * \return Whether the call was successfully performed.
  162. *
  163. * NOTE: This method does not need a current isolate and must not have the
  164. * vm-isolate being the current isolate. It must be called after
  165. * Dart_Initialize() and before Dart_Cleanup().
  166. */
  167. DART_EXPORT bool Dart_InvokeVMServiceMethod(uint8_t* request_json,
  168. intptr_t request_json_length,
  169. uint8_t** response_json,
  170. intptr_t* response_json_length,
  171. char** error);
  172. /*
  173. * ========
  174. * Event Streams
  175. * ========
  176. */
  177. /**
  178. * A callback invoked when the VM service gets a request to listen to
  179. * some stream.
  180. *
  181. * \return Returns true iff the embedder supports the named stream id.
  182. */
  183. typedef bool (*Dart_ServiceStreamListenCallback)(const char* stream_id);
  184. /**
  185. * A callback invoked when the VM service gets a request to cancel
  186. * some stream.
  187. */
  188. typedef void (*Dart_ServiceStreamCancelCallback)(const char* stream_id);
  189. /**
  190. * Adds VM service stream callbacks.
  191. *
  192. * \param listen_callback A function pointer to a listen callback function.
  193. * A listen callback function should not be already set when this function
  194. * is called. A NULL value removes the existing listen callback function
  195. * if any.
  196. *
  197. * \param cancel_callback A function pointer to a cancel callback function.
  198. * A cancel callback function should not be already set when this function
  199. * is called. A NULL value removes the existing cancel callback function
  200. * if any.
  201. *
  202. * \return Success if the callbacks were added. Otherwise, returns an
  203. * error handle.
  204. */
  205. DART_EXPORT char* Dart_SetServiceStreamCallbacks(
  206. Dart_ServiceStreamListenCallback listen_callback,
  207. Dart_ServiceStreamCancelCallback cancel_callback);
  208. /**
  209. * Sends a data event to clients of the VM Service.
  210. *
  211. * A data event is used to pass an array of bytes to subscribed VM
  212. * Service clients. For example, in the standalone embedder, this is
  213. * function used to provide WriteEvents on the Stdout and Stderr
  214. * streams.
  215. *
  216. * If the embedder passes in a stream id for which no client is
  217. * subscribed, then the event is ignored.
  218. *
  219. * \param stream_id The id of the stream on which to post the event.
  220. *
  221. * \param event_kind A string identifying what kind of event this is.
  222. * For example, 'WriteEvent'.
  223. *
  224. * \param bytes A pointer to an array of bytes.
  225. *
  226. * \param bytes_length The length of the byte array.
  227. *
  228. * \return NULL if the arguments are well formed. Otherwise, returns an
  229. * error string. The caller is responsible for freeing the error message.
  230. */
  231. DART_EXPORT char* Dart_ServiceSendDataEvent(const char* stream_id,
  232. const char* event_kind,
  233. const uint8_t* bytes,
  234. intptr_t bytes_length);
  235. /*
  236. * ========
  237. * Reload support
  238. * ========
  239. *
  240. * These functions are used to implement reloading in the Dart VM.
  241. * This is an experimental feature, so embedders should be prepared
  242. * for these functions to change.
  243. */
  244. /**
  245. * A callback which determines whether the file at some url has been
  246. * modified since some time. If the file cannot be found, true should
  247. * be returned.
  248. */
  249. typedef bool (*Dart_FileModifiedCallback)(const char* url, int64_t since);
  250. DART_EXPORT char* Dart_SetFileModifiedCallback(
  251. Dart_FileModifiedCallback file_modified_callback);
  252. /**
  253. * Returns true if isolate is currently reloading.
  254. */
  255. DART_EXPORT bool Dart_IsReloading();
  256. /*
  257. * ========
  258. * Timeline
  259. * ========
  260. */
  261. /**
  262. * Enable tracking of specified timeline category. This is operational
  263. * only when systrace timeline functionality is turned on.
  264. *
  265. * \param categories A comma separated list of categories that need to
  266. * be enabled, the categories are
  267. * "all" : All categories
  268. * "API" - Execution of Dart C API functions
  269. * "Compiler" - Execution of Dart JIT compiler
  270. * "CompilerVerbose" - More detailed Execution of Dart JIT compiler
  271. * "Dart" - Execution of Dart code
  272. * "Debugger" - Execution of Dart debugger
  273. * "Embedder" - Execution of Dart embedder code
  274. * "GC" - Execution of Dart Garbage Collector
  275. * "Isolate" - Dart Isolate lifecycle execution
  276. * "VM" - Execution in Dart VM runtime code
  277. * "" - None
  278. *
  279. * When "all" is specified all the categories are enabled.
  280. * When a comma separated list of categories is specified, the categories
  281. * that are specified will be enabled and the rest will be disabled.
  282. * When "" is specified all the categories are disabled.
  283. * The category names are case sensitive.
  284. * eg: Dart_EnableTimelineCategory("all");
  285. * Dart_EnableTimelineCategory("GC,API,Isolate");
  286. * Dart_EnableTimelineCategory("GC,Debugger,Dart");
  287. *
  288. * \return True if the categories were successfully enabled, False otherwise.
  289. */
  290. DART_EXPORT bool Dart_SetEnabledTimelineCategory(const char* categories);
  291. /**
  292. * Returns a timestamp in microseconds. This timestamp is suitable for
  293. * passing into the timeline system, and uses the same monotonic clock
  294. * as dart:developer's Timeline.now.
  295. *
  296. * \return A timestamp that can be passed to the timeline system.
  297. */
  298. DART_EXPORT int64_t Dart_TimelineGetMicros();
  299. /**
  300. * Returns a raw timestamp in from the monotonic clock.
  301. *
  302. * \return A raw timestamp from the monotonic clock.
  303. */
  304. DART_EXPORT int64_t Dart_TimelineGetTicks();
  305. /**
  306. * Returns the frequency of the monotonic clock.
  307. *
  308. * \return The frequency of the monotonic clock.
  309. */
  310. DART_EXPORT int64_t Dart_TimelineGetTicksFrequency();
  311. typedef enum {
  312. Dart_Timeline_Event_Begin, // Phase = 'B'.
  313. Dart_Timeline_Event_End, // Phase = 'E'.
  314. Dart_Timeline_Event_Instant, // Phase = 'i'.
  315. Dart_Timeline_Event_Duration, // Phase = 'X'.
  316. Dart_Timeline_Event_Async_Begin, // Phase = 'b'.
  317. Dart_Timeline_Event_Async_End, // Phase = 'e'.
  318. Dart_Timeline_Event_Async_Instant, // Phase = 'n'.
  319. Dart_Timeline_Event_Counter, // Phase = 'C'.
  320. Dart_Timeline_Event_Flow_Begin, // Phase = 's'.
  321. Dart_Timeline_Event_Flow_Step, // Phase = 't'.
  322. Dart_Timeline_Event_Flow_End, // Phase = 'f'.
  323. } Dart_Timeline_Event_Type;
  324. /**
  325. * Add a timeline event to the embedder stream.
  326. *
  327. * DEPRECATED: this function will be removed in Dart SDK v3.2.
  328. *
  329. * \param label The name of the event. Its lifetime must extend at least until
  330. * Dart_Cleanup.
  331. * \param timestamp0 The first timestamp of the event.
  332. * \param timestamp1_or_id When reporting an event of type
  333. * |Dart_Timeline_Event_Duration|, the second (end) timestamp of the event
  334. * should be passed through |timestamp1_or_id|. When reporting an event of
  335. * type |Dart_Timeline_Event_Async_Begin|, |Dart_Timeline_Event_Async_End|,
  336. * or |Dart_Timeline_Event_Async_Instant|, the async ID associated with the
  337. * event should be passed through |timestamp1_or_id|. When reporting an
  338. * event of type |Dart_Timeline_Event_Flow_Begin|,
  339. * |Dart_Timeline_Event_Flow_Step|, or |Dart_Timeline_Event_Flow_End|, the
  340. * flow ID associated with the event should be passed through
  341. * |timestamp1_or_id|. When reporting an event of type
  342. * |Dart_Timeline_Event_Begin| or |Dart_Timeline_Event_End|, the event ID
  343. * associated with the event should be passed through |timestamp1_or_id|.
  344. * Note that this event ID will only be used by the MacOS recorder. The
  345. * argument to |timestamp1_or_id| will not be used when reporting events of
  346. * other types.
  347. * \param argument_count The number of argument names and values.
  348. * \param argument_names An array of names of the arguments. The lifetime of the
  349. * names must extend at least until Dart_Cleanup. The array may be reclaimed
  350. * when this call returns.
  351. * \param argument_values An array of values of the arguments. The values and
  352. * the array may be reclaimed when this call returns.
  353. */
  354. DART_EXPORT void Dart_TimelineEvent(const char* label,
  355. int64_t timestamp0,
  356. int64_t timestamp1_or_id,
  357. Dart_Timeline_Event_Type type,
  358. intptr_t argument_count,
  359. const char** argument_names,
  360. const char** argument_values);
  361. /**
  362. * Add a timeline event to the embedder stream.
  363. *
  364. * Note regarding flow events: events must be associated with flow IDs in two
  365. * different ways to allow flow events to be serialized correctly in both
  366. * Chrome's JSON trace event format and Perfetto's proto trace format. Events
  367. * of type |Dart_Timeline_Event_Flow_Begin|, |Dart_Timeline_Event_Flow_Step|,
  368. * and |Dart_Timeline_Event_Flow_End| must be reported to support serialization
  369. * in Chrome's trace format. The |flow_ids| argument must be supplied when
  370. * reporting events of type |Dart_Timeline_Event_Begin|,
  371. * |Dart_Timeline_Event_Duration|, |Dart_Timeline_Event_Instant|,
  372. * |Dart_Timeline_Event_Async_Begin|, and |Dart_Timeline_Event_Async_Instant| to
  373. * support serialization in Perfetto's proto format.
  374. *
  375. * \param label The name of the event. Its lifetime must extend at least until
  376. * Dart_Cleanup.
  377. * \param timestamp0 The first timestamp of the event.
  378. * \param timestamp1_or_id When reporting an event of type
  379. * |Dart_Timeline_Event_Duration|, the second (end) timestamp of the event
  380. * should be passed through |timestamp1_or_id|. When reporting an event of
  381. * type |Dart_Timeline_Event_Async_Begin|, |Dart_Timeline_Event_Async_End|,
  382. * or |Dart_Timeline_Event_Async_Instant|, the async ID associated with the
  383. * event should be passed through |timestamp1_or_id|. When reporting an
  384. * event of type |Dart_Timeline_Event_Flow_Begin|,
  385. * |Dart_Timeline_Event_Flow_Step|, or |Dart_Timeline_Event_Flow_End|, the
  386. * flow ID associated with the event should be passed through
  387. * |timestamp1_or_id|. When reporting an event of type
  388. * |Dart_Timeline_Event_Begin| or |Dart_Timeline_Event_End|, the event ID
  389. * associated with the event should be passed through |timestamp1_or_id|.
  390. * Note that this event ID will only be used by the MacOS recorder. The
  391. * argument to |timestamp1_or_id| will not be used when reporting events of
  392. * other types.
  393. * \param flow_id_count The number of flow IDs associated with this event.
  394. * \param flow_ids An array of flow IDs associated with this event. The array
  395. * may be reclaimed when this call returns.
  396. * \param argument_count The number of argument names and values.
  397. * \param argument_names An array of names of the arguments. The lifetime of the
  398. * names must extend at least until Dart_Cleanup. The array may be reclaimed
  399. * when this call returns.
  400. * \param argument_values An array of values of the arguments. The values and
  401. * the array may be reclaimed when this call returns.
  402. */
  403. DART_EXPORT void Dart_RecordTimelineEvent(const char* label,
  404. int64_t timestamp0,
  405. int64_t timestamp1_or_id,
  406. intptr_t flow_id_count,
  407. const int64_t* flow_ids,
  408. Dart_Timeline_Event_Type type,
  409. intptr_t argument_count,
  410. const char** argument_names,
  411. const char** argument_values);
  412. /**
  413. * Associates a name with the current thread. This name will be used to name
  414. * threads in the timeline. Can only be called after a call to Dart_Initialize.
  415. *
  416. * \param name The name of the thread.
  417. */
  418. DART_EXPORT void Dart_SetThreadName(const char* name);
  419. typedef struct {
  420. const char* name;
  421. const char* value;
  422. } Dart_TimelineRecorderEvent_Argument;
  423. #define DART_TIMELINE_RECORDER_CURRENT_VERSION (0x00000002)
  424. typedef struct {
  425. /* Set to DART_TIMELINE_RECORDER_CURRENT_VERSION */
  426. int32_t version;
  427. /* The event's type / phase. */
  428. Dart_Timeline_Event_Type type;
  429. /* The event's timestamp according to the same clock as
  430. * Dart_TimelineGetMicros. For a duration event, this is the beginning time.
  431. */
  432. int64_t timestamp0;
  433. /**
  434. * For a duration event, this is the end time. For an async event, this is the
  435. * async ID. For a flow event, this is the flow ID. For a begin or end event,
  436. * this is the event ID (which is only referenced by the MacOS recorder).
  437. */
  438. int64_t timestamp1_or_id;
  439. /* The current isolate of the event, as if by Dart_GetMainPortId, or
  440. * ILLEGAL_PORT if the event had no current isolate. */
  441. Dart_Port isolate;
  442. /* The current isolate group of the event, as if by
  443. * Dart_CurrentIsolateGroupId, or ILLEGAL_PORT if the event had no current
  444. * isolate group. */
  445. Dart_IsolateGroupId isolate_group;
  446. /* The callback data associated with the isolate if any. */
  447. void* isolate_data;
  448. /* The callback data associated with the isolate group if any. */
  449. void* isolate_group_data;
  450. /* The name / label of the event. */
  451. const char* label;
  452. /* The stream / category of the event. */
  453. const char* stream;
  454. intptr_t argument_count;
  455. Dart_TimelineRecorderEvent_Argument* arguments;
  456. } Dart_TimelineRecorderEvent;
  457. /**
  458. * Callback provided by the embedder to handle the completion of timeline
  459. * events.
  460. *
  461. * \param event A timeline event that has just been completed. The VM keeps
  462. * ownership of the event and any field in it (i.e., the embedder should copy
  463. * any values it needs after the callback returns).
  464. */
  465. typedef void (*Dart_TimelineRecorderCallback)(
  466. Dart_TimelineRecorderEvent* event);
  467. /**
  468. * Register a `Dart_TimelineRecorderCallback` to be called as timeline events
  469. * are completed.
  470. *
  471. * The callback will be invoked without a current isolate.
  472. *
  473. * The callback will be invoked on the thread completing the event. Because
  474. * `Dart_TimelineEvent` may be called by any thread, the callback may be called
  475. * on any thread.
  476. *
  477. * The callback may be invoked at any time after `Dart_Initialize` is called and
  478. * before `Dart_Cleanup` returns.
  479. *
  480. * If multiple callbacks are registered, only the last callback registered
  481. * will be remembered. Providing a NULL callback will clear the registration
  482. * (i.e., a NULL callback produced a no-op instead of a crash).
  483. *
  484. * Setting a callback is insufficient to receive events through the callback. The
  485. * VM flag `timeline_recorder` must also be set to `callback`.
  486. */
  487. DART_EXPORT void Dart_SetTimelineRecorderCallback(
  488. Dart_TimelineRecorderCallback callback);
  489. /*
  490. * =======
  491. * Metrics
  492. * =======
  493. */
  494. /**
  495. * Return metrics gathered for the VM and individual isolates.
  496. */
  497. DART_EXPORT int64_t
  498. Dart_IsolateGroupHeapOldUsedMetric(Dart_IsolateGroup group); // Byte
  499. DART_EXPORT int64_t
  500. Dart_IsolateGroupHeapOldCapacityMetric(Dart_IsolateGroup group); // Byte
  501. DART_EXPORT int64_t
  502. Dart_IsolateGroupHeapOldExternalMetric(Dart_IsolateGroup group); // Byte
  503. DART_EXPORT int64_t
  504. Dart_IsolateGroupHeapNewUsedMetric(Dart_IsolateGroup group); // Byte
  505. DART_EXPORT int64_t
  506. Dart_IsolateGroupHeapNewCapacityMetric(Dart_IsolateGroup group); // Byte
  507. DART_EXPORT int64_t
  508. Dart_IsolateGroupHeapNewExternalMetric(Dart_IsolateGroup group); // Byte
  509. /*
  510. * ========
  511. * UserTags
  512. * ========
  513. */
  514. /*
  515. * Gets the current isolate's currently set UserTag instance.
  516. *
  517. * \return The currently set UserTag instance.
  518. */
  519. DART_EXPORT Dart_Handle Dart_GetCurrentUserTag();
  520. /*
  521. * Gets the current isolate's default UserTag instance.
  522. *
  523. * \return The default UserTag with label 'Default'
  524. */
  525. DART_EXPORT Dart_Handle Dart_GetDefaultUserTag();
  526. /*
  527. * Creates a new UserTag instance.
  528. *
  529. * \param label The name of the new UserTag.
  530. *
  531. * \return The newly created UserTag instance or an error handle.
  532. */
  533. DART_EXPORT Dart_Handle Dart_NewUserTag(const char* label);
  534. /*
  535. * Updates the current isolate's UserTag to a new value.
  536. *
  537. * \param user_tag The UserTag to be set as the current UserTag.
  538. *
  539. * \return The previously set UserTag instance or an error handle.
  540. */
  541. DART_EXPORT Dart_Handle Dart_SetCurrentUserTag(Dart_Handle user_tag);
  542. /*
  543. * Returns the label of a given UserTag instance.
  544. *
  545. * \param user_tag The UserTag from which the label will be retrieved.
  546. *
  547. * \return The UserTag's label. NULL if the user_tag is invalid. The caller is
  548. * responsible for freeing the returned label.
  549. */
  550. DART_EXPORT DART_WARN_UNUSED_RESULT char* Dart_GetUserTagLabel(
  551. Dart_Handle user_tag);
  552. /*
  553. * =======
  554. * Heap Snapshot
  555. * =======
  556. */
  557. /**
  558. * Callback provided by the caller of `Dart_WriteHeapSnapshot` which is
  559. * used to write out chunks of the requested heap snapshot.
  560. *
  561. * \param context An opaque context which was passed to `Dart_WriteHeapSnapshot`
  562. * together with this callback.
  563. *
  564. * \param buffer Pointer to the buffer containing a chunk of the snapshot.
  565. * The callback owns the buffer and needs to `free` it.
  566. *
  567. * \param size Number of bytes in the `buffer` to be written.
  568. *
  569. * \param is_last Set to `true` for the last chunk. The callback will not
  570. * be invoked again after it was invoked once with `is_last` set to `true`.
  571. */
  572. typedef void (*Dart_HeapSnapshotWriteChunkCallback)(void* context,
  573. uint8_t* buffer,
  574. intptr_t size,
  575. bool is_last);
  576. /**
  577. * Generate heap snapshot of the current isolate group and stream it into the
  578. * given `callback`. VM would produce snapshot in chunks and send these chunks
  579. * one by one back to the embedder by invoking the provided `callback`.
  580. *
  581. * This API enables embedder to stream snapshot into a file or socket without
  582. * allocating a buffer to hold the whole snapshot in memory.
  583. *
  584. * The isolate group will be paused for the duration of this operation.
  585. *
  586. * \param write Callback used to write chunks of the heap snapshot.
  587. *
  588. * \param context Opaque context which would be passed on each invocation of
  589. * `write` callback.
  590. *
  591. * \returns `nullptr` if the operation is successful otherwise error message.
  592. * Caller owns error message string and needs to `free` it.
  593. */
  594. DART_EXPORT char* Dart_WriteHeapSnapshot(
  595. Dart_HeapSnapshotWriteChunkCallback write,
  596. void* context);
  597. #endif // RUNTIME_INCLUDE_DART_TOOLS_API_H_