Flutter Engine
The Flutter Engine
Loading...
Searching...
No Matches
dart_api.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file
3 * for details. All rights reserved. Use of this source code is governed by a
4 * BSD-style license that can be found in the LICENSE file.
5 */
6
7#ifndef RUNTIME_INCLUDE_DART_API_H_
8#define RUNTIME_INCLUDE_DART_API_H_
9
10/** \mainpage Dart Embedding API Reference
11 *
12 * This reference describes the Dart Embedding API, which is used to embed the
13 * Dart Virtual Machine within C/C++ applications.
14 *
15 * This reference is generated from the header include/dart_api.h.
16 */
17
18/* __STDC_FORMAT_MACROS has to be defined before including <inttypes.h> to
19 * enable platform independent printf format specifiers. */
20#ifndef __STDC_FORMAT_MACROS
21#define __STDC_FORMAT_MACROS
22#endif
23
24#include <assert.h>
25#include <inttypes.h>
26#include <stdbool.h>
27
28#if defined(__Fuchsia__)
29#include <zircon/types.h>
30#endif
31
32#ifdef __cplusplus
33#define DART_EXTERN_C extern "C"
34#else
35#define DART_EXTERN_C extern
36#endif
37
38#if defined(__CYGWIN__)
39#error Tool chain and platform not supported.
40#elif defined(_WIN32)
41#if defined(DART_SHARED_LIB)
42#define DART_EXPORT DART_EXTERN_C __declspec(dllexport)
43#else
44#define DART_EXPORT DART_EXTERN_C
45#endif
46#else
47#if __GNUC__ >= 4
48#if defined(DART_SHARED_LIB)
49#define DART_EXPORT \
50 DART_EXTERN_C __attribute__((visibility("default"))) __attribute((used))
51#else
52#define DART_EXPORT DART_EXTERN_C
53#endif
54#else
55#error Tool chain not supported.
56#endif
57#endif
58
59#if __GNUC__
60#define DART_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
61#define DART_DEPRECATED(msg) __attribute__((deprecated(msg)))
62#elif _MSC_VER
63#define DART_WARN_UNUSED_RESULT _Check_return_
64#define DART_DEPRECATED(msg) __declspec(deprecated(msg))
65#else
66#define DART_WARN_UNUSED_RESULT
67#define DART_DEPRECATED(msg)
68#endif
69
70/*
71 * =======
72 * Handles
73 * =======
74 */
75
76/**
77 * An isolate is the unit of concurrency in Dart. Each isolate has
78 * its own memory and thread of control. No state is shared between
79 * isolates. Instead, isolates communicate by message passing.
80 *
81 * Each thread keeps track of its current isolate, which is the
82 * isolate which is ready to execute on the current thread. The
83 * current isolate may be NULL, in which case no isolate is ready to
84 * execute. Most of the Dart apis require there to be a current
85 * isolate in order to function without error. The current isolate is
86 * set by any call to Dart_CreateIsolateGroup or Dart_EnterIsolate.
87 */
88typedef struct _Dart_Isolate* Dart_Isolate;
89typedef struct _Dart_IsolateGroup* Dart_IsolateGroup;
90
91/**
92 * An object reference managed by the Dart VM garbage collector.
93 *
94 * Because the garbage collector may move objects, it is unsafe to
95 * refer to objects directly. Instead, we refer to objects through
96 * handles, which are known to the garbage collector and updated
97 * automatically when the object is moved. Handles should be passed
98 * by value (except in cases like out-parameters) and should never be
99 * allocated on the heap.
100 *
101 * Most functions in the Dart Embedding API return a handle. When a
102 * function completes normally, this will be a valid handle to an
103 * object in the Dart VM heap. This handle may represent the result of
104 * the operation or it may be a special valid handle used merely to
105 * indicate successful completion. Note that a valid handle may in
106 * some cases refer to the null object.
107 *
108 * --- Error handles ---
109 *
110 * When a function encounters a problem that prevents it from
111 * completing normally, it returns an error handle (See Dart_IsError).
112 * An error handle has an associated error message that gives more
113 * details about the problem (See Dart_GetError).
114 *
115 * There are four kinds of error handles that can be produced,
116 * depending on what goes wrong:
117 *
118 * - Api error handles are produced when an api function is misused.
119 * This happens when a Dart embedding api function is called with
120 * invalid arguments or in an invalid context.
121 *
122 * - Unhandled exception error handles are produced when, during the
123 * execution of Dart code, an exception is thrown but not caught.
124 * Prototypically this would occur during a call to Dart_Invoke, but
125 * it can occur in any function which triggers the execution of Dart
126 * code (for example, Dart_ToString).
127 *
128 * An unhandled exception error provides access to an exception and
129 * stacktrace via the functions Dart_ErrorGetException and
130 * Dart_ErrorGetStackTrace.
131 *
132 * - Compilation error handles are produced when, during the execution
133 * of Dart code, a compile-time error occurs. As above, this can
134 * occur in any function which triggers the execution of Dart code.
135 *
136 * - Fatal error handles are produced when the system wants to shut
137 * down the current isolate.
138 *
139 * --- Propagating errors ---
140 *
141 * When an error handle is returned from the top level invocation of
142 * Dart code in a program, the embedder must handle the error as they
143 * see fit. Often, the embedder will print the error message produced
144 * by Dart_Error and exit the program.
145 *
146 * When an error is returned while in the body of a native function,
147 * it can be propagated up the call stack by calling
148 * Dart_PropagateError, Dart_SetReturnValue, or Dart_ThrowException.
149 * Errors should be propagated unless there is a specific reason not
150 * to. If an error is not propagated then it is ignored. For
151 * example, if an unhandled exception error is ignored, that
152 * effectively "catches" the unhandled exception. Fatal errors must
153 * always be propagated.
154 *
155 * When an error is propagated, any current scopes created by
156 * Dart_EnterScope will be exited.
157 *
158 * Using Dart_SetReturnValue to propagate an exception is somewhat
159 * more convenient than using Dart_PropagateError, and should be
160 * preferred for reasons discussed below.
161 *
162 * Dart_PropagateError and Dart_ThrowException do not return. Instead
163 * they transfer control non-locally using a setjmp-like mechanism.
164 * This can be inconvenient if you have resources that you need to
165 * clean up before propagating the error.
166 *
167 * When relying on Dart_PropagateError, we often return error handles
168 * rather than propagating them from helper functions. Consider the
169 * following contrived example:
170 *
171 * 1 Dart_Handle isLongStringHelper(Dart_Handle arg) {
172 * 2 intptr_t* length = 0;
173 * 3 result = Dart_StringLength(arg, &length);
174 * 4 if (Dart_IsError(result)) {
175 * 5 return result;
176 * 6 }
177 * 7 return Dart_NewBoolean(length > 100);
178 * 8 }
179 * 9
180 * 10 void NativeFunction_isLongString(Dart_NativeArguments args) {
181 * 11 Dart_EnterScope();
182 * 12 AllocateMyResource();
183 * 13 Dart_Handle arg = Dart_GetNativeArgument(args, 0);
184 * 14 Dart_Handle result = isLongStringHelper(arg);
185 * 15 if (Dart_IsError(result)) {
186 * 16 FreeMyResource();
187 * 17 Dart_PropagateError(result);
188 * 18 abort(); // will not reach here
189 * 19 }
190 * 20 Dart_SetReturnValue(result);
191 * 21 FreeMyResource();
192 * 22 Dart_ExitScope();
193 * 23 }
194 *
195 * In this example, we have a native function which calls a helper
196 * function to do its work. On line 5, the helper function could call
197 * Dart_PropagateError, but that would not give the native function a
198 * chance to call FreeMyResource(), causing a leak. Instead, the
199 * helper function returns the error handle to the caller, giving the
200 * caller a chance to clean up before propagating the error handle.
201 *
202 * When an error is propagated by calling Dart_SetReturnValue, the
203 * native function will be allowed to complete normally and then the
204 * exception will be propagated only once the native call
205 * returns. This can be convenient, as it allows the C code to clean
206 * up normally.
207 *
208 * The example can be written more simply using Dart_SetReturnValue to
209 * propagate the error.
210 *
211 * 1 Dart_Handle isLongStringHelper(Dart_Handle arg) {
212 * 2 intptr_t* length = 0;
213 * 3 result = Dart_StringLength(arg, &length);
214 * 4 if (Dart_IsError(result)) {
215 * 5 return result
216 * 6 }
217 * 7 return Dart_NewBoolean(length > 100);
218 * 8 }
219 * 9
220 * 10 void NativeFunction_isLongString(Dart_NativeArguments args) {
221 * 11 Dart_EnterScope();
222 * 12 AllocateMyResource();
223 * 13 Dart_Handle arg = Dart_GetNativeArgument(args, 0);
224 * 14 Dart_SetReturnValue(isLongStringHelper(arg));
225 * 15 FreeMyResource();
226 * 16 Dart_ExitScope();
227 * 17 }
228 *
229 * In this example, the call to Dart_SetReturnValue on line 14 will
230 * either return the normal return value or the error (potentially
231 * generated on line 3). The call to FreeMyResource on line 15 will
232 * execute in either case.
233 *
234 * --- Local and persistent handles ---
235 *
236 * Local handles are allocated within the current scope (see
237 * Dart_EnterScope) and go away when the current scope exits. Unless
238 * otherwise indicated, callers should assume that all functions in
239 * the Dart embedding api return local handles.
240 *
241 * Persistent handles are allocated within the current isolate. They
242 * can be used to store objects across scopes. Persistent handles have
243 * the lifetime of the current isolate unless they are explicitly
244 * deallocated (see Dart_DeletePersistentHandle).
245 * The type Dart_Handle represents a handle (both local and persistent).
246 * The type Dart_PersistentHandle is a Dart_Handle and it is used to
247 * document that a persistent handle is expected as a parameter to a call
248 * or the return value from a call is a persistent handle.
249 *
250 * FinalizableHandles are persistent handles which are auto deleted when
251 * the object is garbage collected. It is never safe to use these handles
252 * unless you know the object is still reachable.
253 *
254 * WeakPersistentHandles are persistent handles which are automatically set
255 * to point Dart_Null when the object is garbage collected. They are not auto
256 * deleted, so it is safe to use them after the object has become unreachable.
257 */
258typedef struct _Dart_Handle* Dart_Handle;
260typedef struct _Dart_WeakPersistentHandle* Dart_WeakPersistentHandle;
261typedef struct _Dart_FinalizableHandle* Dart_FinalizableHandle;
262// These structs are versioned by DART_API_DL_MAJOR_VERSION, bump the
263// version when changing this struct.
264
265typedef void (*Dart_HandleFinalizer)(void* isolate_callback_data, void* peer);
266
267/**
268 * Is this an error handle?
269 *
270 * Requires there to be a current isolate.
271 */
273
274/**
275 * Is this an api error handle?
276 *
277 * Api error handles are produced when an api function is misused.
278 * This happens when a Dart embedding api function is called with
279 * invalid arguments or in an invalid context.
280 *
281 * Requires there to be a current isolate.
282 */
284
285/**
286 * Is this an unhandled exception error handle?
287 *
288 * Unhandled exception error handles are produced when, during the
289 * execution of Dart code, an exception is thrown but not caught.
290 * This can occur in any function which triggers the execution of Dart
291 * code.
292 *
293 * See Dart_ErrorGetException and Dart_ErrorGetStackTrace.
294 *
295 * Requires there to be a current isolate.
296 */
298
299/**
300 * Is this a compilation error handle?
301 *
302 * Compilation error handles are produced when, during the execution
303 * of Dart code, a compile-time error occurs. This can occur in any
304 * function which triggers the execution of Dart code.
305 *
306 * Requires there to be a current isolate.
307 */
309
310/**
311 * Is this a fatal error handle?
312 *
313 * Fatal error handles are produced when the system wants to shut down
314 * the current isolate.
315 *
316 * Requires there to be a current isolate.
317 */
319
320/**
321 * Gets the error message from an error handle.
322 *
323 * Requires there to be a current isolate.
324 *
325 * \return A C string containing an error message if the handle is
326 * error. An empty C string ("") if the handle is valid. This C
327 * String is scope allocated and is only valid until the next call
328 * to Dart_ExitScope.
329*/
331
332/**
333 * Is this an error handle for an unhandled exception?
334 */
336
337/**
338 * Gets the exception Object from an unhandled exception error handle.
339 */
341
342/**
343 * Gets the stack trace Object from an unhandled exception error handle.
344 */
346
347/**
348 * Produces an api error handle with the provided error message.
349 *
350 * Requires there to be a current isolate.
351 *
352 * \param error the error message.
353 */
356
357/**
358 * Produces a new unhandled exception error handle.
359 *
360 * Requires there to be a current isolate.
361 *
362 * \param exception An instance of a Dart object to be thrown or
363 * an ApiError or CompilationError handle.
364 * When an ApiError or CompilationError handle is passed in
365 * a string object of the error message is created and it becomes
366 * the Dart object to be thrown.
367 */
369
370/**
371 * Propagates an error.
372 *
373 * If the provided handle is an unhandled exception error, this
374 * function will cause the unhandled exception to be rethrown. This
375 * will proceed in the standard way, walking up Dart frames until an
376 * appropriate 'catch' block is found, executing 'finally' blocks,
377 * etc.
378 *
379 * If the error is not an unhandled exception error, we will unwind
380 * the stack to the next C frame. Intervening Dart frames will be
381 * discarded; specifically, 'finally' blocks will not execute. This
382 * is the standard way that compilation errors (and the like) are
383 * handled by the Dart runtime.
384 *
385 * In either case, when an error is propagated any current scopes
386 * created by Dart_EnterScope will be exited.
387 *
388 * See the additional discussion under "Propagating Errors" at the
389 * beginning of this file.
390 *
391 * \param handle An error handle (See Dart_IsError)
392 *
393 * On success, this function does not return. On failure, the
394 * process is terminated.
395 */
397
398/**
399 * Converts an object to a string.
400 *
401 * May generate an unhandled exception error.
402 *
403 * \return The converted string if no error occurs during
404 * the conversion. If an error does occur, an error handle is
405 * returned.
406 */
408
409/**
410 * Checks to see if two handles refer to identically equal objects.
411 *
412 * If both handles refer to instances, this is equivalent to using the top-level
413 * function identical() from dart:core. Otherwise, returns whether the two
414 * argument handles refer to the same object.
415 *
416 * \param obj1 An object to be compared.
417 * \param obj2 An object to be compared.
418 *
419 * \return True if the objects are identically equal. False otherwise.
420 */
422
423/**
424 * Allocates a handle in the current scope from a persistent handle.
425 */
427
428/**
429 * Allocates a handle in the current scope from a weak persistent handle.
430 *
431 * This will be a handle to Dart_Null if the object has been garbage collected.
432 */
435
436/**
437 * Allocates a persistent handle for an object.
438 *
439 * This handle has the lifetime of the current isolate unless it is
440 * explicitly deallocated by calling Dart_DeletePersistentHandle.
441 *
442 * Requires there to be a current isolate.
443 */
445
446/**
447 * Assign value of local handle to a persistent handle.
448 *
449 * Requires there to be a current isolate.
450 *
451 * \param obj1 A persistent handle whose value needs to be set.
452 * \param obj2 An object whose value needs to be set to the persistent handle.
453 */
455 Dart_Handle obj2);
456
457/**
458 * Deallocates a persistent handle.
459 *
460 * Requires there to be a current isolate group.
461 */
463
464/**
465 * Allocates a weak persistent handle for an object.
466 *
467 * This handle has the lifetime of the current isolate. The handle can also be
468 * explicitly deallocated by calling Dart_DeleteWeakPersistentHandle.
469 *
470 * If the object becomes unreachable the callback is invoked with the peer as
471 * argument. The callback can be executed on any thread, will have a current
472 * isolate group, but will not have a current isolate. The callback can only
473 * call Dart_DeletePersistentHandle or Dart_DeleteWeakPersistentHandle. This
474 * gives the embedder the ability to cleanup data associated with the object.
475 * The handle will point to the Dart_Null object after the finalizer has been
476 * run. It is illegal to call into the VM with any other Dart_* functions from
477 * the callback. If the handle is deleted before the object becomes
478 * unreachable, the callback is never invoked.
479 *
480 * Requires there to be a current isolate.
481 *
482 * \param object An object with identity.
483 * \param peer A pointer to a native object or NULL. This value is
484 * provided to callback when it is invoked.
485 * \param external_allocation_size The number of externally allocated
486 * bytes for peer. Used to inform the garbage collector.
487 * \param callback A function pointer that will be invoked sometime
488 * after the object is garbage collected, unless the handle has been deleted.
489 * A valid callback needs to be specified it cannot be NULL.
490 *
491 * \return The weak persistent handle or NULL. NULL is returned in case of bad
492 * parameters.
493 */
496 void* peer,
497 intptr_t external_allocation_size,
499
500/**
501 * Deletes the given weak persistent [object] handle.
502 *
503 * Requires there to be a current isolate group.
504 */
507
508/**
509 * Allocates a finalizable handle for an object.
510 *
511 * This handle has the lifetime of the current isolate group unless the object
512 * pointed to by the handle is garbage collected, in this case the VM
513 * automatically deletes the handle after invoking the callback associated
514 * with the handle. The handle can also be explicitly deallocated by
515 * calling Dart_DeleteFinalizableHandle.
516 *
517 * If the object becomes unreachable the callback is invoked with the
518 * the peer as argument. The callback can be executed on any thread, will have
519 * an isolate group, but will not have a current isolate. The callback can only
520 * call Dart_DeletePersistentHandle or Dart_DeleteWeakPersistentHandle.
521 * This gives the embedder the ability to cleanup data associated with the
522 * object and clear out any cached references to the handle. All references to
523 * this handle after the callback will be invalid. It is illegal to call into
524 * the VM with any other Dart_* functions from the callback. If the handle is
525 * deleted before the object becomes unreachable, the callback is never
526 * invoked.
527 *
528 * Requires there to be a current isolate.
529 *
530 * \param object An object with identity.
531 * \param peer A pointer to a native object or NULL. This value is
532 * provided to callback when it is invoked.
533 * \param external_allocation_size The number of externally allocated
534 * bytes for peer. Used to inform the garbage collector.
535 * \param callback A function pointer that will be invoked sometime
536 * after the object is garbage collected, unless the handle has been deleted.
537 * A valid callback needs to be specified it cannot be NULL.
538 *
539 * \return The finalizable handle or NULL. NULL is returned in case of bad
540 * parameters.
541 */
544 void* peer,
545 intptr_t external_allocation_size,
547
548/**
549 * Deletes the given finalizable [object] handle.
550 *
551 * The caller has to provide the actual Dart object the handle was created from
552 * to prove the object (and therefore the finalizable handle) is still alive.
553 *
554 * Requires there to be a current isolate.
555 */
557 Dart_Handle strong_ref_to_object);
558
559
560/*
561 * ==========================
562 * Initialization and Globals
563 * ==========================
564 */
565
566/**
567 * Gets the version string for the Dart VM.
568 *
569 * The version of the Dart VM can be accessed without initializing the VM.
570 *
571 * \return The version string for the embedded Dart VM.
572 */
574
575/**
576 * Isolate specific flags are set when creating a new isolate using the
577 * Dart_IsolateFlags structure.
578 *
579 * Current version of flags is encoded in a 32-bit integer with 16 bits used
580 * for each part.
581 */
582
583#define DART_FLAGS_CURRENT_VERSION (0x0000000d)
584
599
600/**
601 * Initialize Dart_IsolateFlags with correct version and default values.
602 */
604
605/**
606 * An isolate creation and initialization callback function.
607 *
608 * This callback, provided by the embedder, is called when the VM
609 * needs to create an isolate. The callback should create an isolate
610 * by calling Dart_CreateIsolateGroup and load any scripts required for
611 * execution.
612 *
613 * This callback may be called on a different thread than the one
614 * running the parent isolate.
615 *
616 * When the function returns NULL, it is the responsibility of this
617 * function to ensure that Dart_ShutdownIsolate has been called if
618 * required (for example, if the isolate was created successfully by
619 * Dart_CreateIsolateGroup() but the root library fails to load
620 * successfully, then the function should call Dart_ShutdownIsolate
621 * before returning).
622 *
623 * When the function returns NULL, the function should set *error to
624 * a malloc-allocated buffer containing a useful error message. The
625 * caller of this function (the VM) will make sure that the buffer is
626 * freed.
627 *
628 * \param script_uri The uri of the main source file or snapshot to load.
629 * Either the URI of the parent isolate set in Dart_CreateIsolateGroup for
630 * Isolate.spawn, or the argument to Isolate.spawnUri canonicalized by the
631 * library tag handler of the parent isolate.
632 * The callback is responsible for loading the program by a call to
633 * Dart_LoadScriptFromKernel.
634 * \param main The name of the main entry point this isolate will
635 * eventually run. This is provided for advisory purposes only to
636 * improve debugging messages. The main function is not invoked by
637 * this function.
638 * \param package_root Ignored.
639 * \param package_config Uri of the package configuration file (either in format
640 * of .packages or .dart_tool/package_config.json) for this isolate
641 * to resolve package imports against. If this parameter is not passed the
642 * package resolution of the parent isolate should be used.
643 * \param flags Default flags for this isolate being spawned. Either inherited
644 * from the spawning isolate or passed as parameters when spawning the
645 * isolate from Dart code.
646 * \param isolate_data The isolate data which was passed to the
647 * parent isolate when it was created by calling Dart_CreateIsolateGroup().
648 * \param error A structure into which the embedder can place a
649 * C string containing an error message in the case of failures.
650 *
651 * \return The embedder returns NULL if the creation and
652 * initialization was not successful and the isolate if successful.
653 */
655 const char* script_uri,
656 const char* main,
657 const char* package_root,
658 const char* package_config,
660 void* isolate_data,
661 char** error);
662
663/**
664 * An isolate initialization callback function.
665 *
666 * This callback, provided by the embedder, is called when the VM has created an
667 * isolate within an existing isolate group (i.e. from the same source as an
668 * existing isolate).
669 *
670 * The callback should setup native resolvers and might want to set a custom
671 * message handler via [Dart_SetMessageNotifyCallback] and mark the isolate as
672 * runnable.
673 *
674 * This callback may be called on a different thread than the one
675 * running the parent isolate.
676 *
677 * When the function returns `false`, it is the responsibility of this
678 * function to ensure that `Dart_ShutdownIsolate` has been called.
679 *
680 * When the function returns `false`, the function should set *error to
681 * a malloc-allocated buffer containing a useful error message. The
682 * caller of this function (the VM) will make sure that the buffer is
683 * freed.
684 *
685 * \param child_isolate_data The callback data to associate with the new
686 * child isolate.
687 * \param error A structure into which the embedder can place a
688 * C string containing an error message in the case the initialization fails.
689 *
690 * \return The embedder returns true if the initialization was successful and
691 * false otherwise (in which case the VM will terminate the isolate).
692 */
693typedef bool (*Dart_InitializeIsolateCallback)(void** child_isolate_data,
694 char** error);
695
696/**
697 * An isolate shutdown callback function.
698 *
699 * This callback, provided by the embedder, is called before the vm
700 * shuts down an isolate. The isolate being shutdown will be the current
701 * isolate. It is safe to run Dart code.
702 *
703 * This function should be used to dispose of native resources that
704 * are allocated to an isolate in order to avoid leaks.
705 *
706 * \param isolate_group_data The same callback data which was passed to the
707 * isolate group when it was created.
708 * \param isolate_data The same callback data which was passed to the isolate
709 * when it was created.
710 */
711typedef void (*Dart_IsolateShutdownCallback)(void* isolate_group_data,
712 void* isolate_data);
713
714/**
715 * An isolate cleanup callback function.
716 *
717 * This callback, provided by the embedder, is called after the vm
718 * shuts down an isolate. There will be no current isolate and it is *not*
719 * safe to run Dart code.
720 *
721 * This function should be used to dispose of native resources that
722 * are allocated to an isolate in order to avoid leaks.
723 *
724 * \param isolate_group_data The same callback data which was passed to the
725 * isolate group when it was created.
726 * \param isolate_data The same callback data which was passed to the isolate
727 * when it was created.
728 */
729typedef void (*Dart_IsolateCleanupCallback)(void* isolate_group_data,
730 void* isolate_data);
731
732/**
733 * An isolate group cleanup callback function.
734 *
735 * This callback, provided by the embedder, is called after the vm
736 * shuts down an isolate group.
737 *
738 * This function should be used to dispose of native resources that
739 * are allocated to an isolate in order to avoid leaks.
740 *
741 * \param isolate_group_data The same callback data which was passed to the
742 * isolate group when it was created.
743 *
744 */
745typedef void (*Dart_IsolateGroupCleanupCallback)(void* isolate_group_data);
746
747/**
748 * A thread start callback function.
749 * This callback, provided by the embedder, is called after a thread in the
750 * vm thread pool starts.
751 * This function could be used to adjust thread priority or attach native
752 * resources to the thread.
753 */
754typedef void (*Dart_ThreadStartCallback)(void);
755
756/**
757 * A thread death callback function.
758 * This callback, provided by the embedder, is called before a thread in the
759 * vm thread pool exits.
760 * This function could be used to dispose of native resources that
761 * are associated and attached to the thread, in order to avoid leaks.
762 */
763typedef void (*Dart_ThreadExitCallback)(void);
764
765/**
766 * Opens a file for reading or writing.
767 *
768 * Callback provided by the embedder for file operations. If the
769 * embedder does not allow file operations this callback can be
770 * NULL.
771 *
772 * \param name The name of the file to open.
773 * \param write A boolean variable which indicates if the file is to
774 * opened for writing. If there is an existing file it needs to truncated.
775 */
776typedef void* (*Dart_FileOpenCallback)(const char* name, bool write);
777
778/**
779 * Read contents of file.
780 *
781 * Callback provided by the embedder for file operations. If the
782 * embedder does not allow file operations this callback can be
783 * NULL.
784 *
785 * \param data Buffer allocated in the callback into which the contents
786 * of the file are read into. It is the responsibility of the caller to
787 * free this buffer.
788 * \param file_length A variable into which the length of the file is returned.
789 * In the case of an error this value would be -1.
790 * \param stream Handle to the opened file.
791 */
792typedef void (*Dart_FileReadCallback)(uint8_t** data,
793 intptr_t* file_length,
794 void* stream);
795
796/**
797 * Write data into file.
798 *
799 * Callback provided by the embedder for file operations. If the
800 * embedder does not allow file operations this callback can be
801 * NULL.
802 *
803 * \param data Buffer which needs to be written into the file.
804 * \param length Length of the buffer.
805 * \param stream Handle to the opened file.
806 */
807typedef void (*Dart_FileWriteCallback)(const void* data,
808 intptr_t length,
809 void* stream);
810
811/**
812 * Closes the opened file.
813 *
814 * Callback provided by the embedder for file operations. If the
815 * embedder does not allow file operations this callback can be
816 * NULL.
817 *
818 * \param stream Handle to the opened file.
819 */
820typedef void (*Dart_FileCloseCallback)(void* stream);
821
822typedef bool (*Dart_EntropySource)(uint8_t* buffer, intptr_t length);
823
824/**
825 * Callback provided by the embedder that is used by the vmservice isolate
826 * to request the asset archive. The asset archive must be an uncompressed tar
827 * archive that is stored in a Uint8List.
828 *
829 * If the embedder has no vmservice isolate assets, the callback can be NULL.
830 *
831 * \return The embedder must return a handle to a Uint8List containing an
832 * uncompressed tar archive or null.
833 */
835
836/**
837 * The current version of the Dart_InitializeFlags. Should be incremented every
838 * time Dart_InitializeFlags changes in a binary incompatible way.
839 */
840#define DART_INITIALIZE_PARAMS_CURRENT_VERSION (0x00000008)
841
842/** Forward declaration */
843struct Dart_CodeObserver;
844
845/**
846 * Callback provided by the embedder that is used by the VM to notify on code
847 * object creation, *before* it is invoked the first time.
848 * This is useful for embedders wanting to e.g. keep track of PCs beyond
849 * the lifetime of the garbage collected code objects.
850 * Note that an address range may be used by more than one code object over the
851 * lifecycle of a process. Clients of this function should record timestamps for
852 * these compilation events and when collecting PCs to disambiguate reused
853 * address ranges.
854 */
855typedef void (*Dart_OnNewCodeCallback)(struct Dart_CodeObserver* observer,
856 const char* name,
857 uintptr_t base,
858 uintptr_t size);
859
865
866/**
867 * Optional callback provided by the embedder that is used by the VM to
868 * implement registration of kernel blobs for the subsequent Isolate.spawnUri
869 * If no callback is provided, the registration of kernel blobs will throw
870 * an error.
871 *
872 * \param kernel_buffer A buffer which contains a kernel program. Callback
873 * should copy the contents of `kernel_buffer` as
874 * it may be freed immediately after registration.
875 * \param kernel_buffer_size The size of `kernel_buffer`.
876 *
877 * \return A C string representing URI which can be later used
878 * to spawn a new isolate. This C String should be scope allocated
879 * or owned by the embedder.
880 * Returns NULL if embedder runs out of memory.
881 */
882typedef const char* (*Dart_RegisterKernelBlobCallback)(
883 const uint8_t* kernel_buffer,
884 intptr_t kernel_buffer_size);
885
886/**
887 * Optional callback provided by the embedder that is used by the VM to
888 * unregister kernel blobs.
889 * If no callback is provided, the unregistration of kernel blobs will throw
890 * an error.
891 *
892 * \param kernel_blob_uri URI of the kernel blob to unregister.
893 */
894typedef void (*Dart_UnregisterKernelBlobCallback)(const char* kernel_blob_uri);
895
896/**
897 * Describes how to initialize the VM. Used with Dart_Initialize.
898 */
899typedef struct {
900 /**
901 * Identifies the version of the struct used by the client.
902 * should be initialized to DART_INITIALIZE_PARAMS_CURRENT_VERSION.
903 */
904 int32_t version;
905
906 /**
907 * A buffer containing snapshot data, or NULL if no snapshot is provided.
908 *
909 * If provided, the buffer must remain valid until Dart_Cleanup returns.
910 */
911 const uint8_t* vm_snapshot_data;
912
913 /**
914 * A buffer containing a snapshot of precompiled instructions, or NULL if
915 * no snapshot is provided.
916 *
917 * If provided, the buffer must remain valid until Dart_Cleanup returns.
918 */
920
921 /**
922 * A function to be called during isolate group creation.
923 * See Dart_IsolateGroupCreateCallback.
924 */
926
927 /**
928 * A function to be called during isolate
929 * initialization inside an existing isolate group.
930 * See Dart_InitializeIsolateCallback.
931 */
933
934 /**
935 * A function to be called right before an isolate is shutdown.
936 * See Dart_IsolateShutdownCallback.
937 */
939
940 /**
941 * A function to be called after an isolate was shutdown.
942 * See Dart_IsolateCleanupCallback.
943 */
945
946 /**
947 * A function to be called after an isolate group is
948 * shutdown. See Dart_IsolateGroupCleanupCallback.
949 */
951
959
960 /**
961 * A function to be called by the service isolate when it requires the
962 * vmservice assets archive. See Dart_GetVMServiceAssetsArchive.
963 */
965
967
968 /**
969 * An external code observer callback function. The observer can be invoked
970 * as early as during the Dart_Initialize() call.
971 */
973
974 /**
975 * Kernel blob registration callback function. See Dart_RegisterKernelBlobCallback.
976 */
978
979 /**
980 * Kernel blob unregistration callback function. See Dart_UnregisterKernelBlobCallback.
981 */
983
984#if defined(__Fuchsia__)
985 /**
986 * The resource needed to use zx_vmo_replace_as_executable. Can be
987 * ZX_HANDLE_INVALID if the process has ambient-replace-as-executable or if
988 * executable memory is not needed (e.g., this is an AOT runtime).
989 */
990 zx_handle_t vmex_resource;
991#endif
993
994/**
995 * Initializes the VM.
996 *
997 * \param params A struct containing initialization information. The version
998 * field of the struct must be DART_INITIALIZE_PARAMS_CURRENT_VERSION.
999 *
1000 * \return NULL if initialization is successful. Returns an error message
1001 * otherwise. The caller is responsible for freeing the error message.
1002 */
1005
1006/**
1007 * Cleanup state in the VM before process termination.
1008 *
1009 * \return NULL if cleanup is successful. Returns an error message otherwise.
1010 * The caller is responsible for freeing the error message.
1011 *
1012 * NOTE: This function must not be called on a thread that was created by the VM
1013 * itself.
1014 */
1016
1017/**
1018 * Sets command line flags. Should be called before Dart_Initialize.
1019 *
1020 * \param argc The length of the arguments array.
1021 * \param argv An array of arguments.
1022 *
1023 * \return NULL if successful. Returns an error message otherwise.
1024 * The caller is responsible for freeing the error message.
1025 *
1026 * NOTE: This call does not store references to the passed in c-strings.
1027 */
1029 const char** argv);
1030
1031/**
1032 * Returns true if the named VM flag is of boolean type, specified, and set to
1033 * true.
1034 *
1035 * \param flag_name The name of the flag without leading punctuation
1036 * (example: "enable_asserts").
1037 */
1038DART_EXPORT bool Dart_IsVMFlagSet(const char* flag_name);
1039
1040/*
1041 * ========
1042 * Isolates
1043 * ========
1044 */
1045
1046/**
1047 * Creates a new isolate. The new isolate becomes the current isolate.
1048 *
1049 * A snapshot can be used to restore the VM quickly to a saved state
1050 * and is useful for fast startup. If snapshot data is provided, the
1051 * isolate will be started using that snapshot data. Requires a core snapshot or
1052 * an app snapshot created by Dart_CreateSnapshot or
1053 * Dart_CreatePrecompiledSnapshot* from a VM with the same version.
1054 *
1055 * Requires there to be no current isolate.
1056 *
1057 * \param script_uri The main source file or snapshot this isolate will load.
1058 * The VM will provide this URI to the Dart_IsolateGroupCreateCallback when a
1059 * child isolate is created by Isolate.spawn. The embedder should use a URI
1060 * that allows it to load the same program into such a child isolate.
1061 * \param name A short name for the isolate to improve debugging messages.
1062 * Typically of the format 'foo.dart:main()'.
1063 * \param isolate_snapshot_data Buffer containing the snapshot data of the
1064 * isolate or NULL if no snapshot is provided. If provided, the buffer must
1065 * remain valid until the isolate shuts down.
1066 * \param isolate_snapshot_instructions Buffer containing the snapshot
1067 * instructions of the isolate or NULL if no snapshot is provided. If
1068 * provided, the buffer must remain valid until the isolate shuts down.
1069 * \param flags Pointer to VM specific flags or NULL for default flags.
1070 * \param isolate_group_data Embedder group data. This data can be obtained
1071 * by calling Dart_IsolateGroupData and will be passed to the
1072 * Dart_IsolateShutdownCallback, Dart_IsolateCleanupCallback, and
1073 * Dart_IsolateGroupCleanupCallback.
1074 * \param isolate_data Embedder data. This data will be passed to
1075 * the Dart_IsolateGroupCreateCallback when new isolates are spawned from
1076 * this parent isolate.
1077 * \param error Returns NULL if creation is successful, an error message
1078 * otherwise. The caller is responsible for calling free() on the error
1079 * message.
1080 *
1081 * \return The new isolate on success, or NULL if isolate creation failed.
1082 */
1084Dart_CreateIsolateGroup(const char* script_uri,
1085 const char* name,
1086 const uint8_t* isolate_snapshot_data,
1087 const uint8_t* isolate_snapshot_instructions,
1089 void* isolate_group_data,
1090 void* isolate_data,
1091 char** error);
1092/**
1093 * Creates a new isolate inside the isolate group of [group_member].
1094 *
1095 * Requires there to be no current isolate.
1096 *
1097 * \param group_member An isolate from the same group into which the newly created
1098 * isolate should be born into. Other threads may not have entered / enter this
1099 * member isolate.
1100 * \param name A short name for the isolate for debugging purposes.
1101 * \param shutdown_callback A callback to be called when the isolate is being
1102 * shutdown (may be NULL).
1103 * \param cleanup_callback A callback to be called when the isolate is being
1104 * cleaned up (may be NULL).
1105 * \param child_isolate_data The embedder-specific data associated with this isolate.
1106 * \param error Set to NULL if creation is successful, set to an error
1107 * message otherwise. The caller is responsible for calling free() on the
1108 * error message.
1109 *
1110 * \return The newly created isolate on success, or NULL if isolate creation
1111 * failed.
1112 *
1113 * If successful, the newly created isolate will become the current isolate.
1114 */
1117 const char* name,
1118 Dart_IsolateShutdownCallback shutdown_callback,
1119 Dart_IsolateCleanupCallback cleanup_callback,
1120 void* child_isolate_data,
1121 char** error);
1122
1123/* TODO(turnidge): Document behavior when there is already a current
1124 * isolate. */
1125
1126/**
1127 * Creates a new isolate from a Dart Kernel file. The new isolate
1128 * becomes the current isolate.
1129 *
1130 * Requires there to be no current isolate.
1131 *
1132 * \param script_uri The main source file or snapshot this isolate will load.
1133 * The VM will provide this URI to the Dart_IsolateGroupCreateCallback when a
1134 * child isolate is created by Isolate.spawn. The embedder should use a URI that
1135 * allows it to load the same program into such a child isolate.
1136 * \param name A short name for the isolate to improve debugging messages.
1137 * Typically of the format 'foo.dart:main()'.
1138 * \param kernel_buffer A buffer which contains a kernel/DIL program. Must
1139 * remain valid until isolate shutdown.
1140 * \param kernel_buffer_size The size of `kernel_buffer`.
1141 * \param flags Pointer to VM specific flags or NULL for default flags.
1142 * \param isolate_group_data Embedder group data. This data can be obtained
1143 * by calling Dart_IsolateGroupData and will be passed to the
1144 * Dart_IsolateShutdownCallback, Dart_IsolateCleanupCallback, and
1145 * Dart_IsolateGroupCleanupCallback.
1146 * \param isolate_data Embedder data. This data will be passed to
1147 * the Dart_IsolateGroupCreateCallback when new isolates are spawned from
1148 * this parent isolate.
1149 * \param error Returns NULL if creation is successful, an error message
1150 * otherwise. The caller is responsible for calling free() on the error
1151 * message.
1152 *
1153 * \return The new isolate on success, or NULL if isolate creation failed.
1154 */
1157 const char* name,
1158 const uint8_t* kernel_buffer,
1159 intptr_t kernel_buffer_size,
1161 void* isolate_group_data,
1162 void* isolate_data,
1163 char** error);
1164/**
1165 * Shuts down the current isolate. After this call, the current isolate is NULL.
1166 * Any current scopes created by Dart_EnterScope will be exited. Invokes the
1167 * shutdown callback and any callbacks of remaining weak persistent handles.
1168 *
1169 * Requires there to be a current isolate.
1170 */
1172/* TODO(turnidge): Document behavior when there is no current isolate. */
1173
1174/**
1175 * Returns the current isolate. Will return NULL if there is no
1176 * current isolate.
1177 */
1179
1180/**
1181 * Returns the callback data associated with the current isolate. This
1182 * data was set when the isolate got created or initialized.
1183 */
1185
1186/**
1187 * Returns the callback data associated with the given isolate. This
1188 * data was set when the isolate got created or initialized.
1189 */
1191
1192/**
1193 * Returns the current isolate group. Will return NULL if there is no
1194 * current isolate group.
1195 */
1197
1198/**
1199 * Returns the callback data associated with the current isolate group. This
1200 * data was passed to the isolate group when it was created.
1201 */
1203
1204/**
1205 * Gets an id that uniquely identifies current isolate group.
1206 *
1207 * It is the responsibility of the caller to free the returned ID.
1208 */
1209typedef int64_t Dart_IsolateGroupId;
1211
1212/**
1213 * Returns the callback data associated with the specified isolate group. This
1214 * data was passed to the isolate when it was created.
1215 * The embedder is responsible for ensuring the consistency of this data
1216 * with respect to the lifecycle of an isolate group.
1217 */
1219
1220/**
1221 * Returns the debugging name for the current isolate.
1222 *
1223 * This name is unique to each isolate and should only be used to make
1224 * debugging messages more comprehensible.
1225 */
1227
1228/**
1229 * Returns the debugging name for the current isolate.
1230 *
1231 * This name is unique to each isolate and should only be used to make
1232 * debugging messages more comprehensible.
1233 *
1234 * The returned string is scope allocated and is only valid until the next call
1235 * to Dart_ExitScope.
1236 */
1238
1239/**
1240 * Returns the ID for an isolate which is used to query the service protocol.
1241 *
1242 * It is the responsibility of the caller to free the returned ID.
1243 */
1245
1246/**
1247 * Enters an isolate. After calling this function,
1248 * the current isolate will be set to the provided isolate.
1249 *
1250 * Requires there to be no current isolate. Multiple threads may not be in
1251 * the same isolate at once.
1252 */
1254
1255/**
1256 * Kills the given isolate.
1257 *
1258 * This function has the same effect as dart:isolate's
1259 * Isolate.kill(priority:immediate).
1260 * It can interrupt ordinary Dart code but not native code. If the isolate is
1261 * in the middle of a long running native function, the isolate will not be
1262 * killed until control returns to Dart.
1263 *
1264 * Does not require a current isolate. It is safe to kill the current isolate if
1265 * there is one.
1266 */
1268
1269/**
1270 * Notifies the VM that the embedder expects to be idle until |deadline|. The VM
1271 * may use this time to perform garbage collection or other tasks to avoid
1272 * delays during execution of Dart code in the future.
1273 *
1274 * |deadline| is measured in microseconds against the system's monotonic time.
1275 * This clock can be accessed via Dart_TimelineGetMicros().
1276 *
1277 * Requires there to be a current isolate.
1278 */
1279DART_EXPORT void Dart_NotifyIdle(int64_t deadline);
1280
1281typedef void (*Dart_HeapSamplingReportCallback)(void* context,
1282 void* data);
1283
1284typedef void* (*Dart_HeapSamplingCreateCallback)(
1285 Dart_Isolate isolate,
1286 Dart_IsolateGroup isolate_group,
1287 const char* cls_name,
1288 intptr_t allocation_size);
1289typedef void (*Dart_HeapSamplingDeleteCallback)(void* data);
1290
1291/**
1292 * Starts the heap sampling profiler for each thread in the VM.
1293 */
1295
1296/*
1297 * Stops the heap sampling profiler for each thread in the VM.
1298 */
1300
1301/* Registers callbacks are invoked once per sampled allocation upon object
1302 * allocation and garbage collection.
1303 *
1304 * |create_callback| can be used to associate additional data with the sampled
1305 * allocation, such as a stack trace. This data pointer will be passed to
1306 * |delete_callback| to allow for proper disposal when the object associated
1307 * with the allocation sample is collected.
1308 *
1309 * The provided callbacks must not call into the VM and should do as little
1310 * work as possible to avoid performance penalities during object allocation and
1311 * garbage collection.
1312 *
1313 * NOTE: It is a fatal error to set either callback to null once they have been
1314 * initialized.
1315 */
1317 Dart_HeapSamplingCreateCallback create_callback,
1318 Dart_HeapSamplingDeleteCallback delete_callback);
1319
1320/*
1321 * Reports the surviving allocation samples for all live isolate groups in the
1322 * VM.
1323 *
1324 * When the callback is invoked:
1325 * - |context| will be the context object provided when invoking
1326 * |Dart_ReportSurvivingAllocations|. This can be safely set to null if not
1327 * required.
1328 * - |heap_size| will be equal to the size of the allocated object associated
1329 * with the sample.
1330 * - |cls_name| will be a C String representing
1331 * the class name of the allocated object. This string is valid for the
1332 * duration of the call to Dart_ReportSurvivingAllocations and can be
1333 * freed by the VM at any point after the method returns.
1334 * - |data| will be set to the data associated with the sample by
1335 * |Dart_HeapSamplingCreateCallback|.
1336 *
1337 * If |force_gc| is true, a full GC will be performed before reporting the
1338 * allocations.
1339 */
1342 void* context,
1343 bool force_gc);
1344
1345/*
1346 * Sets the average heap sampling rate based on a number of |bytes| for each
1347 * thread.
1348 *
1349 * In other words, approximately every |bytes| allocated will create a sample.
1350 * Defaults to 512 KiB.
1351 */
1353
1354/**
1355 * Notifies the VM that the embedder expects the application's working set has
1356 * recently shrunk significantly and is not expected to rise in the near future.
1357 * The VM may spend O(heap-size) time performing clean up work.
1358 *
1359 * Requires there to be a current isolate.
1360 */
1362
1363/**
1364 * Notifies the VM that the system is running low on memory.
1365 *
1366 * Does not require a current isolate. Only valid after calling Dart_Initialize.
1367 */
1369
1370typedef enum {
1371 /**
1372 * Balanced
1373 */
1375 /**
1376 * Optimize for low latency, at the expense of throughput and memory overhead
1377 * by performing work in smaller batches (requiring more overhead) or by
1378 * delaying work (requiring more memory). An embedder should not remain in
1379 * this mode indefinitely.
1380 */
1382 /**
1383 * Optimize for high throughput, at the expense of latency and memory overhead
1384 * by performing work in larger batches with more intervening growth.
1385 */
1387 /**
1388 * Optimize for low memory, at the expensive of throughput and latency by more
1389 * frequently performing work.
1390 */
1393
1394/**
1395 * Set the desired performance trade-off.
1396 *
1397 * Requires a current isolate.
1398 *
1399 * Returns the previous performance mode.
1400 */
1403
1404/**
1405 * Starts the CPU sampling profiler.
1406 */
1408
1409/**
1410 * Stops the CPU sampling profiler.
1411 *
1412 * Note that some profile samples might still be taken after this function
1413 * returns due to the asynchronous nature of the implementation on some
1414 * platforms.
1415 */
1417
1418/**
1419 * Notifies the VM that the current thread should not be profiled until a
1420 * matching call to Dart_ThreadEnableProfiling is made.
1421 *
1422 * NOTE: By default, if a thread has entered an isolate it will be profiled.
1423 * This function should be used when an embedder knows a thread is about
1424 * to make a blocking call and wants to avoid unnecessary interrupts by
1425 * the profiler.
1426 */
1428
1429/**
1430 * Notifies the VM that the current thread should be profiled.
1431 *
1432 * NOTE: It is only legal to call this function *after* calling
1433 * Dart_ThreadDisableProfiling.
1434 *
1435 * NOTE: By default, if a thread has entered an isolate it will be profiled.
1436 */
1438
1439/**
1440 * Register symbol information for the Dart VM's profiler and crash dumps.
1441 *
1442 * This consumes the output of //topaz/runtime/dart/profiler_symbols, which
1443 * should be treated as opaque.
1444 */
1445DART_EXPORT void Dart_AddSymbols(const char* dso_name,
1446 void* buffer,
1447 intptr_t buffer_size);
1448
1449/**
1450 * Exits an isolate. After this call, Dart_CurrentIsolate will
1451 * return NULL.
1452 *
1453 * Requires there to be a current isolate.
1454 */
1456/* TODO(turnidge): We don't want users of the api to be able to exit a
1457 * "pure" dart isolate. Implement and document. */
1458
1459/**
1460 * Creates a full snapshot of the current isolate heap.
1461 *
1462 * A full snapshot is a compact representation of the dart vm isolate heap
1463 * and dart isolate heap states. These snapshots are used to initialize
1464 * the vm isolate on startup and fast initialization of an isolate.
1465 * A Snapshot of the heap is created before any dart code has executed.
1466 *
1467 * Requires there to be a current isolate. Not available in the precompiled
1468 * runtime (check Dart_IsPrecompiledRuntime).
1469 *
1470 * \param vm_snapshot_data_buffer Returns a pointer to a buffer containing the
1471 * vm snapshot. This buffer is scope allocated and is only valid
1472 * until the next call to Dart_ExitScope.
1473 * \param vm_snapshot_data_size Returns the size of vm_snapshot_data_buffer.
1474 * \param isolate_snapshot_data_buffer Returns a pointer to a buffer containing
1475 * the isolate snapshot. This buffer is scope allocated and is only valid
1476 * until the next call to Dart_ExitScope.
1477 * \param isolate_snapshot_data_size Returns the size of
1478 * isolate_snapshot_data_buffer.
1479 * \param is_core Create a snapshot containing core libraries.
1480 * Such snapshot should be agnostic to null safety mode.
1481 *
1482 * \return A valid handle if no error occurs during the operation.
1483 */
1485Dart_CreateSnapshot(uint8_t** vm_snapshot_data_buffer,
1486 intptr_t* vm_snapshot_data_size,
1487 uint8_t** isolate_snapshot_data_buffer,
1488 intptr_t* isolate_snapshot_data_size,
1489 bool is_core);
1490
1491/**
1492 * Returns whether the buffer contains a kernel file.
1493 *
1494 * \param buffer Pointer to a buffer that might contain a kernel binary.
1495 * \param buffer_size Size of the buffer.
1496 *
1497 * \return Whether the buffer contains a kernel binary (full or partial).
1498 */
1499DART_EXPORT bool Dart_IsKernel(const uint8_t* buffer, intptr_t buffer_size);
1500
1501/**
1502 * Make isolate runnable.
1503 *
1504 * When isolates are spawned, this function is used to indicate that
1505 * the creation and initialization (including script loading) of the
1506 * isolate is complete and the isolate can start.
1507 * This function expects there to be no current isolate.
1508 *
1509 * \param isolate The isolate to be made runnable.
1510 *
1511 * \return NULL if successful. Returns an error message otherwise. The caller
1512 * is responsible for freeing the error message.
1513 */
1515 Dart_Isolate isolate);
1516
1517/*
1518 * ==================
1519 * Messages and Ports
1520 * ==================
1521 */
1522
1523/**
1524 * A port is used to send or receive inter-isolate messages
1525 */
1526typedef int64_t Dart_Port;
1527
1528/**
1529 * ILLEGAL_PORT is a port number guaranteed never to be associated with a valid
1530 * port.
1531 */
1532#define ILLEGAL_PORT ((Dart_Port)0)
1533
1534/**
1535 * A message notification callback.
1536 *
1537 * This callback allows the embedder to provide a custom wakeup mechanism for
1538 * the delivery of inter-isolate messages. This function is called once per
1539 * message on an arbitrary thread. It is the responsibility of the embedder to
1540 * eventually call Dart_HandleMessage once per callback received with the
1541 * destination isolate set as the current isolate to process the message.
1542 */
1543typedef void (*Dart_MessageNotifyCallback)(Dart_Isolate destination_isolate);
1544
1545/**
1546 * Allows embedders to provide a custom wakeup mechanism for the delivery of
1547 * inter-isolate messages. This setting only applies to the current isolate.
1548 *
1549 * This mechanism is optional: if not provided, the isolate will be scheduled on
1550 * a VM-managed thread pool. An embedder should provide this callback if it
1551 * wants to run an isolate on a specific thread or to interleave handling of
1552 * inter-isolate messages with other event sources.
1553 *
1554 * Most embedders will only call this function once, before isolate
1555 * execution begins. If this function is called after isolate
1556 * execution begins, the embedder is responsible for threading issues.
1557 */
1559 Dart_MessageNotifyCallback message_notify_callback);
1560/* TODO(turnidge): Consider moving this to isolate creation so that it
1561 * is impossible to mess up. */
1562
1563/**
1564 * Query the current message notify callback for the isolate.
1565 *
1566 * \return The current message notify callback for the isolate.
1567 */
1569
1570/**
1571 * The VM's default message handler supports pausing an isolate before it
1572 * processes the first message and right after the it processes the isolate's
1573 * final message. This can be controlled for all isolates by two VM flags:
1574 *
1575 * `--pause-isolates-on-start`
1576 * `--pause-isolates-on-exit`
1577 *
1578 * Additionally, Dart_SetShouldPauseOnStart and Dart_SetShouldPauseOnExit can be
1579 * used to control this behaviour on a per-isolate basis.
1580 *
1581 * When an embedder is using a Dart_MessageNotifyCallback the embedder
1582 * needs to cooperate with the VM so that the service protocol can report
1583 * accurate information about isolates and so that tools such as debuggers
1584 * work reliably.
1585 *
1586 * The following functions can be used to implement pausing on start and exit.
1587 */
1588
1589/**
1590 * If the VM flag `--pause-isolates-on-start` was passed this will be true.
1591 *
1592 * \return A boolean value indicating if pause on start was requested.
1593 */
1595
1596/**
1597 * Override the VM flag `--pause-isolates-on-start` for the current isolate.
1598 *
1599 * \param should_pause Should the isolate be paused on start?
1600 *
1601 * NOTE: This must be called before Dart_IsolateMakeRunnable.
1602 */
1604
1605/**
1606 * Is the current isolate paused on start?
1607 *
1608 * \return A boolean value indicating if the isolate is paused on start.
1609 */
1611
1612/**
1613 * Called when the embedder has paused the current isolate on start and when
1614 * the embedder has resumed the isolate.
1615 *
1616 * \param paused Is the isolate paused on start?
1617 */
1619
1620/**
1621 * If the VM flag `--pause-isolates-on-exit` was passed this will be true.
1622 *
1623 * \return A boolean value indicating if pause on exit was requested.
1624 */
1626
1627/**
1628 * Override the VM flag `--pause-isolates-on-exit` for the current isolate.
1629 *
1630 * \param should_pause Should the isolate be paused on exit?
1631 *
1632 */
1634
1635/**
1636 * Is the current isolate paused on exit?
1637 *
1638 * \return A boolean value indicating if the isolate is paused on exit.
1639 */
1641
1642/**
1643 * Called when the embedder has paused the current isolate on exit and when
1644 * the embedder has resumed the isolate.
1645 *
1646 * \param paused Is the isolate paused on exit?
1647 */
1649
1650/**
1651 * Called when the embedder has caught a top level unhandled exception error
1652 * in the current isolate.
1653 *
1654 * NOTE: It is illegal to call this twice on the same isolate without first
1655 * clearing the sticky error to null.
1656 *
1657 * \param error The unhandled exception error.
1658 */
1660
1661/**
1662 * Does the current isolate have a sticky error?
1663 */
1665
1666/**
1667 * Gets the sticky error for the current isolate.
1668 *
1669 * \return A handle to the sticky error object or null.
1670 */
1672
1673/**
1674 * Handles the next pending message for the current isolate.
1675 *
1676 * May generate an unhandled exception error.
1677 *
1678 * \return A valid handle if no error occurs during the operation.
1679 */
1681
1682/**
1683 * Drains the microtask queue, then blocks the calling thread until the current
1684 * isolate receives a message, then handles all messages.
1685 *
1686 * \param timeout_millis When non-zero, the call returns after the indicated
1687 number of milliseconds even if no message was received.
1688 * \return A valid handle if no error occurs, otherwise an error handle.
1689 */
1691Dart_WaitForEvent(int64_t timeout_millis);
1692
1693/**
1694 * Handles any pending messages for the vm service for the current
1695 * isolate.
1696 *
1697 * This function may be used by an embedder at a breakpoint to avoid
1698 * pausing the vm service.
1699 *
1700 * This function can indirectly cause the message notify callback to
1701 * be called.
1702 *
1703 * \return true if the vm service requests the program resume
1704 * execution, false otherwise
1705 */
1707
1708/**
1709 * Does the current isolate have pending service messages?
1710 *
1711 * \return true if the isolate has pending service messages, false otherwise.
1712 */
1714
1715/**
1716 * Processes any incoming messages for the current isolate.
1717 *
1718 * This function may only be used when the embedder has not provided
1719 * an alternate message delivery mechanism with
1720 * Dart_SetMessageCallbacks. It is provided for convenience.
1721 *
1722 * This function waits for incoming messages for the current
1723 * isolate. As new messages arrive, they are handled using
1724 * Dart_HandleMessage. The routine exits when all ports to the
1725 * current isolate are closed.
1726 *
1727 * \return A valid handle if the run loop exited successfully. If an
1728 * exception or other error occurs while processing messages, an
1729 * error handle is returned.
1730 */
1732
1733/**
1734 * Lets the VM run message processing for the isolate.
1735 *
1736 * This function expects there to a current isolate and the current isolate
1737 * must not have an active api scope. The VM will take care of making the
1738 * isolate runnable (if not already), handles its message loop and will take
1739 * care of shutting the isolate down once it's done.
1740 *
1741 * \param errors_are_fatal Whether uncaught errors should be fatal.
1742 * \param on_error_port A port to notify on uncaught errors (or ILLEGAL_PORT).
1743 * \param on_exit_port A port to notify on exit (or ILLEGAL_PORT).
1744 * \param error A non-NULL pointer which will hold an error message if the call
1745 * fails. The error has to be free()ed by the caller.
1746 *
1747 * \return If successful the VM takes ownership of the isolate and takes care
1748 * of its message loop. If not successful the caller retains ownership of the
1749 * isolate.
1750 */
1752 bool errors_are_fatal,
1753 Dart_Port on_error_port,
1754 Dart_Port on_exit_port,
1755 char** error);
1756
1757/* TODO(turnidge): Should this be removed from the public api? */
1758
1759/**
1760 * Gets the main port id for the current isolate.
1761 */
1763
1764/**
1765 * Does the current isolate have live ReceivePorts?
1766 *
1767 * A ReceivePort is live when it has not been closed.
1768 */
1770
1771/**
1772 * Posts a message for some isolate. The message is a serialized
1773 * object.
1774 *
1775 * Requires there to be a current isolate.
1776 *
1777 * For posting messages outside of an isolate see \ref Dart_PostCObject.
1778 *
1779 * \param port_id The destination port.
1780 * \param object An object from the current isolate.
1781 *
1782 * \return True if the message was posted.
1783 */
1785
1786/**
1787 * Returns a new SendPort with the provided port id.
1788 *
1789 * \param port_id The destination port.
1790 *
1791 * \return A new SendPort if no errors occurs. Otherwise returns
1792 * an error handle.
1793 */
1795
1796/**
1797 * Gets the SendPort id for the provided SendPort.
1798 * \param port A SendPort object whose id is desired.
1799 * \param port_id Returns the id of the SendPort.
1800 * \return Success if no error occurs. Otherwise returns
1801 * an error handle.
1802 */
1804 Dart_Port* port_id);
1805
1806/*
1807 * ======
1808 * Scopes
1809 * ======
1810 */
1811
1812/**
1813 * Enters a new scope.
1814 *
1815 * All new local handles will be created in this scope. Additionally,
1816 * some functions may return "scope allocated" memory which is only
1817 * valid within this scope.
1818 *
1819 * Requires there to be a current isolate.
1820 */
1822
1823/**
1824 * Exits a scope.
1825 *
1826 * The previous scope (if any) becomes the current scope.
1827 *
1828 * Requires there to be a current isolate.
1829 */
1831
1832/**
1833 * The Dart VM uses "zone allocation" for temporary structures. Zones
1834 * support very fast allocation of small chunks of memory. The chunks
1835 * cannot be deallocated individually, but instead zones support
1836 * deallocating all chunks in one fast operation.
1837 *
1838 * This function makes it possible for the embedder to allocate
1839 * temporary data in the VMs zone allocator.
1840 *
1841 * Zone allocation is possible:
1842 * 1. when inside a scope where local handles can be allocated
1843 * 2. when processing a message from a native port in a native port
1844 * handler
1845 *
1846 * All the memory allocated this way will be reclaimed either on the
1847 * next call to Dart_ExitScope or when the native port handler exits.
1848 *
1849 * \param size Size of the memory to allocate.
1850 *
1851 * \return A pointer to the allocated memory. NULL if allocation
1852 * failed. Failure might due to is no current VM zone.
1853 */
1854DART_EXPORT uint8_t* Dart_ScopeAllocate(intptr_t size);
1855
1856/*
1857 * =======
1858 * Objects
1859 * =======
1860 */
1861
1862/**
1863 * Returns the null object.
1864 *
1865 * \return A handle to the null object.
1866 */
1868
1869/**
1870 * Is this object null?
1871 */
1873
1874/**
1875 * Returns the empty string object.
1876 *
1877 * \return A handle to the empty string object.
1878 */
1880
1881/**
1882 * Returns types that are not classes, and which therefore cannot be looked up
1883 * as library members by Dart_GetType.
1884 *
1885 * \return A handle to the dynamic, void or Never type.
1886 */
1890
1891/**
1892 * Checks if the two objects are equal.
1893 *
1894 * The result of the comparison is returned through the 'equal'
1895 * parameter. The return value itself is used to indicate success or
1896 * failure, not equality.
1897 *
1898 * May generate an unhandled exception error.
1899 *
1900 * \param obj1 An object to be compared.
1901 * \param obj2 An object to be compared.
1902 * \param equal Returns the result of the equality comparison.
1903 *
1904 * \return A valid handle if no error occurs during the comparison.
1905 */
1907 Dart_Handle obj2,
1908 bool* equal);
1909
1910/**
1911 * Is this object an instance of some type?
1912 *
1913 * The result of the test is returned through the 'instanceof' parameter.
1914 * The return value itself is used to indicate success or failure.
1915 *
1916 * \param object An object.
1917 * \param type A type.
1918 * \param instanceof Return true if 'object' is an instance of type 'type'.
1919 *
1920 * \return A valid handle if no error occurs during the operation.
1921 */
1924 bool* instanceof);
1925
1926/**
1927 * Query object type.
1928 *
1929 * \param object Some Object.
1930 *
1931 * \return true if Object is of the specified type.
1932 */
1939DART_EXPORT bool Dart_IsStringLatin1(Dart_Handle object); /* (ISO-8859-1) */
1952
1953/*
1954 * =========
1955 * Instances
1956 * =========
1957 */
1958
1959/*
1960 * For the purposes of the embedding api, not all objects returned are
1961 * Dart language objects. Within the api, we use the term 'Instance'
1962 * to indicate handles which refer to true Dart language objects.
1963 *
1964 * TODO(turnidge): Reorganize the "Object" section above, pulling down
1965 * any functions that more properly belong here. */
1966
1967/**
1968 * Gets the type of a Dart language object.
1969 *
1970 * \param instance Some Dart object.
1971 *
1972 * \return If no error occurs, the type is returned. Otherwise an
1973 * error handle is returned.
1974 */
1976
1977/**
1978 * Returns the name for the provided class type.
1979 *
1980 * \return A valid string handle if no error occurs during the
1981 * operation.
1982 */
1984
1985/**
1986 * Returns the name for the provided function or method.
1987 *
1988 * \return A valid string handle if no error occurs during the
1989 * operation.
1990 */
1992
1993/**
1994 * Returns a handle to the owner of a function.
1995 *
1996 * The owner of an instance method or a static method is its defining
1997 * class. The owner of a top-level function is its defining
1998 * library. The owner of the function of a non-implicit closure is the
1999 * function of the method or closure that defines the non-implicit
2000 * closure.
2001 *
2002 * \return A valid handle to the owner of the function, or an error
2003 * handle if the argument is not a valid handle to a function.
2004 */
2006
2007/**
2008 * Determines whether a function handle refers to a static function
2009 * of method.
2010 *
2011 * For the purposes of the embedding API, a top-level function is
2012 * implicitly declared static.
2013 *
2014 * \param function A handle to a function or method declaration.
2015 * \param is_static Returns whether the function or method is declared static.
2016 *
2017 * \return A valid handle if no error occurs during the operation.
2018 */
2020 bool* is_static);
2021
2022/**
2023 * Is this object a closure resulting from a tear-off (closurized method)?
2024 *
2025 * Returns true for closures produced when an ordinary method is accessed
2026 * through a getter call. Returns false otherwise, in particular for closures
2027 * produced from local function declarations.
2028 *
2029 * \param object Some Object.
2030 *
2031 * \return true if Object is a tear-off.
2032 */
2034
2035/**
2036 * Retrieves the function of a closure.
2037 *
2038 * \return A handle to the function of the closure, or an error handle if the
2039 * argument is not a closure.
2040 */
2042
2043/**
2044 * Returns a handle to the library which contains class.
2045 *
2046 * \return A valid handle to the library with owns class, null if the class
2047 * has no library or an error handle if the argument is not a valid handle
2048 * to a class type.
2049 */
2051
2052/*
2053 * =============================
2054 * Numbers, Integers and Doubles
2055 * =============================
2056 */
2057
2058/**
2059 * Does this Integer fit into a 64-bit signed integer?
2060 *
2061 * \param integer An integer.
2062 * \param fits Returns true if the integer fits into a 64-bit signed integer.
2063 *
2064 * \return A valid handle if no error occurs during the operation.
2065 */
2067 bool* fits);
2068
2069/**
2070 * Does this Integer fit into a 64-bit unsigned integer?
2071 *
2072 * \param integer An integer.
2073 * \param fits Returns true if the integer fits into a 64-bit unsigned integer.
2074 *
2075 * \return A valid handle if no error occurs during the operation.
2076 */
2078 bool* fits);
2079
2080/**
2081 * Returns an Integer with the provided value.
2082 *
2083 * \param value The value of the integer.
2084 *
2085 * \return The Integer object if no error occurs. Otherwise returns
2086 * an error handle.
2087 */
2089
2090/**
2091 * Returns an Integer with the provided value.
2092 *
2093 * \param value The unsigned value of the integer.
2094 *
2095 * \return The Integer object if no error occurs. Otherwise returns
2096 * an error handle.
2097 */
2099
2100/**
2101 * Returns an Integer with the provided value.
2102 *
2103 * \param value The value of the integer represented as a C string
2104 * containing a hexadecimal number.
2105 *
2106 * \return The Integer object if no error occurs. Otherwise returns
2107 * an error handle.
2108 */
2110
2111/**
2112 * Gets the value of an Integer.
2113 *
2114 * The integer must fit into a 64-bit signed integer, otherwise an error occurs.
2115 *
2116 * \param integer An Integer.
2117 * \param value Returns the value of the Integer.
2118 *
2119 * \return A valid handle if no error occurs during the operation.
2120 */
2122 int64_t* value);
2123
2124/**
2125 * Gets the value of an Integer.
2126 *
2127 * The integer must fit into a 64-bit unsigned integer, otherwise an
2128 * error occurs.
2129 *
2130 * \param integer An Integer.
2131 * \param value Returns the value of the Integer.
2132 *
2133 * \return A valid handle if no error occurs during the operation.
2134 */
2136 uint64_t* value);
2137
2138/**
2139 * Gets the value of an integer as a hexadecimal C string.
2140 *
2141 * \param integer An Integer.
2142 * \param value Returns the value of the Integer as a hexadecimal C
2143 * string. This C string is scope allocated and is only valid until
2144 * the next call to Dart_ExitScope.
2145 *
2146 * \return A valid handle if no error occurs during the operation.
2147 */
2149 const char** value);
2150
2151/**
2152 * Returns a Double with the provided value.
2153 *
2154 * \param value A double.
2155 *
2156 * \return The Double object if no error occurs. Otherwise returns
2157 * an error handle.
2158 */
2160
2161/**
2162 * Gets the value of a Double
2163 *
2164 * \param double_obj A Double
2165 * \param value Returns the value of the Double.
2166 *
2167 * \return A valid handle if no error occurs during the operation.
2168 */
2170
2171/**
2172 * Returns a closure of static function 'function_name' in the class 'class_name'
2173 * in the exported namespace of specified 'library'.
2174 *
2175 * \param library Library object
2176 * \param cls_type Type object representing a Class
2177 * \param function_name Name of the static function in the class
2178 *
2179 * \return A valid Dart instance if no error occurs during the operation.
2180 */
2182 Dart_Handle cls_type,
2183 Dart_Handle function_name);
2184
2185/*
2186 * ========
2187 * Booleans
2188 * ========
2189 */
2190
2191/**
2192 * Returns the True object.
2193 *
2194 * Requires there to be a current isolate.
2195 *
2196 * \return A handle to the True object.
2197 */
2199
2200/**
2201 * Returns the False object.
2202 *
2203 * Requires there to be a current isolate.
2204 *
2205 * \return A handle to the False object.
2206 */
2208
2209/**
2210 * Returns a Boolean with the provided value.
2211 *
2212 * \param value true or false.
2213 *
2214 * \return The Boolean object if no error occurs. Otherwise returns
2215 * an error handle.
2216 */
2218
2219/**
2220 * Gets the value of a Boolean
2221 *
2222 * \param boolean_obj A Boolean
2223 * \param value Returns the value of the Boolean.
2224 *
2225 * \return A valid handle if no error occurs during the operation.
2226 */
2228
2229/*
2230 * =======
2231 * Strings
2232 * =======
2233 */
2234
2235/**
2236 * Gets the length of a String.
2237 *
2238 * \param str A String.
2239 * \param length Returns the length of the String.
2240 *
2241 * \return A valid handle if no error occurs during the operation.
2242 */
2244
2245/**
2246 * Gets the length of UTF-8 encoded representation for a string.
2247 *
2248 * \param str A String.
2249 * \param length Returns the length of UTF-8 encoded representation for string.
2250 *
2251 * \return A valid handle if no error occurs during the operation.
2252 */
2254 intptr_t* length);
2255
2256/**
2257 * Returns a String built from the provided C string
2258 * (There is an implicit assumption that the C string passed in contains
2259 * UTF-8 encoded characters and '\0' is considered as a termination
2260 * character).
2261 *
2262 * \param str A C String
2263 *
2264 * \return The String object if no error occurs. Otherwise returns
2265 * an error handle.
2266 */
2268/* TODO(turnidge): Document what happens when we run out of memory
2269 * during this call. */
2270
2271/**
2272 * Returns a String built from an array of UTF-8 encoded characters.
2273 *
2274 * \param utf8_array An array of UTF-8 encoded characters.
2275 * \param length The length of the codepoints array.
2276 *
2277 * \return The String object if no error occurs. Otherwise returns
2278 * an error handle.
2279 */
2281 intptr_t length);
2282
2283/**
2284 * Returns a String built from an array of UTF-16 encoded characters.
2285 *
2286 * \param utf16_array An array of UTF-16 encoded characters.
2287 * \param length The length of the codepoints array.
2288 *
2289 * \return The String object if no error occurs. Otherwise returns
2290 * an error handle.
2291 */
2293 intptr_t length);
2294
2295/**
2296 * Returns a String built from an array of UTF-32 encoded characters.
2297 *
2298 * \param utf32_array An array of UTF-32 encoded characters.
2299 * \param length The length of the codepoints array.
2300 *
2301 * \return The String object if no error occurs. Otherwise returns
2302 * an error handle.
2303 */
2305 intptr_t length);
2306
2307/**
2308 * Returns a String which references an external array of
2309 * Latin-1 (ISO-8859-1) encoded characters.
2310 *
2311 * \param latin1_array Array of Latin-1 encoded characters. This must not move.
2312 * \param length The length of the characters array.
2313 * \param peer An external pointer to associate with this string.
2314 * \param external_allocation_size The number of externally allocated
2315 * bytes for peer. Used to inform the garbage collector.
2316 * \param callback A callback to be called when this string is finalized.
2317 *
2318 * \return The String object if no error occurs. Otherwise returns
2319 * an error handle.
2320 */
2322Dart_NewExternalLatin1String(const uint8_t* latin1_array,
2323 intptr_t length,
2324 void* peer,
2325 intptr_t external_allocation_size,
2327
2328/**
2329 * Returns a String which references an external array of UTF-16 encoded
2330 * characters.
2331 *
2332 * \param utf16_array An array of UTF-16 encoded characters. This must not move.
2333 * \param length The length of the characters array.
2334 * \param peer An external pointer to associate with this string.
2335 * \param external_allocation_size The number of externally allocated
2336 * bytes for peer. Used to inform the garbage collector.
2337 * \param callback A callback to be called when this string is finalized.
2338 *
2339 * \return The String object if no error occurs. Otherwise returns
2340 * an error handle.
2341 */
2343Dart_NewExternalUTF16String(const uint16_t* utf16_array,
2344 intptr_t length,
2345 void* peer,
2346 intptr_t external_allocation_size,
2348
2349/**
2350 * Gets the C string representation of a String.
2351 * (It is a sequence of UTF-8 encoded values with a '\0' termination.)
2352 *
2353 * \param str A string.
2354 * \param cstr Returns the String represented as a C string.
2355 * This C string is scope allocated and is only valid until
2356 * the next call to Dart_ExitScope.
2357 *
2358 * \return A valid handle if no error occurs during the operation.
2359 */
2361 const char** cstr);
2362
2363/**
2364 * Gets a UTF-8 encoded representation of a String.
2365 *
2366 * Any unpaired surrogate code points in the string will be converted as
2367 * replacement characters (U+FFFD, 0xEF 0xBF 0xBD in UTF-8). If you need
2368 * to preserve unpaired surrogates, use the Dart_StringToUTF16 function.
2369 *
2370 * \param str A string.
2371 * \param utf8_array Returns the String represented as UTF-8 code
2372 * units. This UTF-8 array is scope allocated and is only valid
2373 * until the next call to Dart_ExitScope.
2374 * \param length Used to return the length of the array which was
2375 * actually used.
2376 *
2377 * \return A valid handle if no error occurs during the operation.
2378 */
2380 uint8_t** utf8_array,
2381 intptr_t* length);
2382
2383/**
2384 * Copies the UTF-8 encoded representation of a String into specified buffer.
2385 *
2386 * Any unpaired surrogate code points in the string will be converted as
2387 * replacement characters (U+FFFD, 0xEF 0xBF 0xBD in UTF-8).
2388 *
2389 * \param str A string.
2390 * \param utf8_array Buffer into which the UTF-8 encoded representation of
2391 * the string is copied into.
2392 * The buffer is allocated and managed by the caller.
2393 * \param length Specifies the length of the buffer passed in.
2394 *
2395 * \return A valid handle if no error occurs during the operation.
2396 */
2398 uint8_t* utf8_array,
2399 intptr_t length);
2400
2401/**
2402 * Gets the data corresponding to the string object. This function returns
2403 * the data only for Latin-1 (ISO-8859-1) string objects. For all other
2404 * string objects it returns an error.
2405 *
2406 * \param str A string.
2407 * \param latin1_array An array allocated by the caller, used to return
2408 * the string data.
2409 * \param length Used to pass in the length of the provided array.
2410 * Used to return the length of the array which was actually used.
2411 *
2412 * \return A valid handle if no error occurs during the operation.
2413 */
2415 uint8_t* latin1_array,
2416 intptr_t* length);
2417
2418/**
2419 * Gets the UTF-16 encoded representation of a string.
2420 *
2421 * \param str A string.
2422 * \param utf16_array An array allocated by the caller, used to return
2423 * the array of UTF-16 encoded characters.
2424 * \param length Used to pass in the length of the provided array.
2425 * Used to return the length of the array which was actually used.
2426 *
2427 * \return A valid handle if no error occurs during the operation.
2428 */
2430 uint16_t* utf16_array,
2431 intptr_t* length);
2432
2433/**
2434 * Gets the storage size in bytes of a String.
2435 *
2436 * \param str A String.
2437 * \param size Returns the storage size in bytes of the String.
2438 * This is the size in bytes needed to store the String.
2439 *
2440 * \return A valid handle if no error occurs during the operation.
2441 */
2443
2444/**
2445 * Retrieves some properties associated with a String.
2446 * Properties retrieved are:
2447 * - character size of the string (one or two byte)
2448 * - length of the string
2449 * - peer pointer of string if it is an external string.
2450 * \param str A String.
2451 * \param char_size Returns the character size of the String.
2452 * \param str_len Returns the length of the String.
2453 * \param peer Returns the peer pointer associated with the String or 0 if
2454 * there is no peer pointer for it.
2455 * \return Success if no error occurs. Otherwise returns
2456 * an error handle.
2457 */
2459 intptr_t* char_size,
2460 intptr_t* str_len,
2461 void** peer);
2462
2463/*
2464 * =====
2465 * Lists
2466 * =====
2467 */
2468
2469/**
2470 * Returns a List<dynamic> of the desired length.
2471 *
2472 * \param length The length of the list.
2473 *
2474 * \return The List object if no error occurs. Otherwise returns
2475 * an error handle.
2476 */
2478
2484
2485// TODO(bkonyi): convert this to use nullable types once NNBD is enabled.
2486/**
2487 * Returns a List of the desired length with the desired legacy element type.
2488 *
2489 * \param element_type_id The type of elements of the list.
2490 * \param length The length of the list.
2491 *
2492 * \return The List object if no error occurs. Otherwise returns an error
2493 * handle.
2494 */
2496 intptr_t length);
2497
2498/**
2499 * Returns a List of the desired length with the desired element type.
2500 *
2501 * \param element_type Handle to a nullable type object. E.g., from
2502 * Dart_GetType or Dart_GetNullableType.
2503 *
2504 * \param length The length of the list.
2505 *
2506 * \return The List object if no error occurs. Otherwise returns
2507 * an error handle.
2508 */
2510 intptr_t length);
2511
2512/**
2513 * Returns a List of the desired length with the desired element type, filled
2514 * with the provided object.
2515 *
2516 * \param element_type Handle to a type object. E.g., from Dart_GetType.
2517 *
2518 * \param fill_object Handle to an object of type 'element_type' that will be
2519 * used to populate the list. This parameter can only be Dart_Null() if the
2520 * length of the list is 0 or 'element_type' is a nullable type.
2521 *
2522 * \param length The length of the list.
2523 *
2524 * \return The List object if no error occurs. Otherwise returns
2525 * an error handle.
2526 */
2528 Dart_Handle fill_object,
2529 intptr_t length);
2530
2531/**
2532 * Gets the length of a List.
2533 *
2534 * May generate an unhandled exception error.
2535 *
2536 * \param list A List.
2537 * \param length Returns the length of the List.
2538 *
2539 * \return A valid handle if no error occurs during the operation.
2540 */
2542
2543/**
2544 * Gets the Object at some index of a List.
2545 *
2546 * If the index is out of bounds, an error occurs.
2547 *
2548 * May generate an unhandled exception error.
2549 *
2550 * \param list A List.
2551 * \param index A valid index into the List.
2552 *
2553 * \return The Object in the List at the specified index if no error
2554 * occurs. Otherwise returns an error handle.
2555 */
2557
2558/**
2559* Gets a range of Objects from a List.
2560*
2561* If any of the requested index values are out of bounds, an error occurs.
2562*
2563* May generate an unhandled exception error.
2564*
2565* \param list A List.
2566* \param offset The offset of the first item to get.
2567* \param length The number of items to get.
2568* \param result A pointer to fill with the objects.
2569*
2570* \return Success if no error occurs during the operation.
2571*/
2573 intptr_t offset,
2574 intptr_t length,
2576
2577/**
2578 * Sets the Object at some index of a List.
2579 *
2580 * If the index is out of bounds, an error occurs.
2581 *
2582 * May generate an unhandled exception error.
2583 *
2584 * \param list A List.
2585 * \param index A valid index into the List.
2586 * \param value The Object to put in the List.
2587 *
2588 * \return A valid handle if no error occurs during the operation.
2589 */
2591 intptr_t index,
2592 Dart_Handle value);
2593
2594/**
2595 * May generate an unhandled exception error.
2596 */
2598 intptr_t offset,
2599 uint8_t* native_array,
2600 intptr_t length);
2601
2602/**
2603 * May generate an unhandled exception error.
2604 */
2606 intptr_t offset,
2607 const uint8_t* native_array,
2608 intptr_t length);
2609
2610/*
2611 * ====
2612 * Maps
2613 * ====
2614 */
2615
2616/**
2617 * Gets the Object at some key of a Map.
2618 *
2619 * May generate an unhandled exception error.
2620 *
2621 * \param map A Map.
2622 * \param key An Object.
2623 *
2624 * \return The value in the map at the specified key, null if the map does not
2625 * contain the key, or an error handle.
2626 */
2628
2629/**
2630 * Returns whether the Map contains a given key.
2631 *
2632 * May generate an unhandled exception error.
2633 *
2634 * \param map A Map.
2635 *
2636 * \return A handle on a boolean indicating whether map contains the key.
2637 * Otherwise returns an error handle.
2638 */
2640
2641/**
2642 * Gets the list of keys of a Map.
2643 *
2644 * May generate an unhandled exception error.
2645 *
2646 * \param map A Map.
2647 *
2648 * \return The list of key Objects if no error occurs. Otherwise returns an
2649 * error handle.
2650 */
2652
2653/*
2654 * ==========
2655 * Typed Data
2656 * ==========
2657 */
2658
2677
2678/**
2679 * Return type if this object is a TypedData object.
2680 *
2681 * \return kInvalid if the object is not a TypedData object or the appropriate
2682 * Dart_TypedData_Type.
2683 */
2685
2686/**
2687 * Return type if this object is an external TypedData object.
2688 *
2689 * \return kInvalid if the object is not an external TypedData object or
2690 * the appropriate Dart_TypedData_Type.
2691 */
2694
2695/**
2696 * Returns a TypedData object of the desired length and type.
2697 *
2698 * \param type The type of the TypedData object.
2699 * \param length The length of the TypedData object (length in type units).
2700 *
2701 * \return The TypedData object if no error occurs. Otherwise returns
2702 * an error handle.
2703 */
2705 intptr_t length);
2706
2707/**
2708 * Returns a TypedData object which references an external data array.
2709 *
2710 * \param type The type of the data array.
2711 * \param data A data array. This array must not move.
2712 * \param length The length of the data array (length in type units).
2713 *
2714 * \return The TypedData object if no error occurs. Otherwise returns
2715 * an error handle.
2716 */
2718 void* data,
2719 intptr_t length);
2720
2721/**
2722 * Returns a TypedData object which references an external data array.
2723 *
2724 * \param type The type of the data array.
2725 * \param data A data array. This array must not move.
2726 * \param length The length of the data array (length in type units).
2727 * \param peer A pointer to a native object or NULL. This value is
2728 * provided to callback when it is invoked.
2729 * \param external_allocation_size The number of externally allocated
2730 * bytes for peer. Used to inform the garbage collector.
2731 * \param callback A function pointer that will be invoked sometime
2732 * after the object is garbage collected, unless the handle has been deleted.
2733 * A valid callback needs to be specified it cannot be NULL.
2734 *
2735 * \return The TypedData object if no error occurs. Otherwise returns
2736 * an error handle.
2737 */
2740 void* data,
2741 intptr_t length,
2742 void* peer,
2743 intptr_t external_allocation_size,
2747 const void* data,
2748 intptr_t length,
2749 void* peer,
2750 intptr_t external_allocation_size,
2752
2753/**
2754 * Returns a ByteBuffer object for the typed data.
2755 *
2756 * \param typed_data The TypedData object.
2757 *
2758 * \return The ByteBuffer object if no error occurs. Otherwise returns
2759 * an error handle.
2760 */
2762
2763/**
2764 * Acquires access to the internal data address of a TypedData object.
2765 *
2766 * \param object The typed data object whose internal data address is to
2767 * be accessed.
2768 * \param type The type of the object is returned here.
2769 * \param data The internal data address is returned here.
2770 * \param len Size of the typed array is returned here.
2771 *
2772 * Notes:
2773 * When the internal address of the object is acquired any calls to a
2774 * Dart API function that could potentially allocate an object or run
2775 * any Dart code will return an error.
2776 *
2777 * Any Dart API functions for accessing the data should not be called
2778 * before the corresponding release. In particular, the object should
2779 * not be acquired again before its release. This leads to undefined
2780 * behavior.
2781 *
2782 * \return Success if the internal data address is acquired successfully.
2783 * Otherwise, returns an error handle.
2784 */
2787 void** data,
2788 intptr_t* len);
2789
2790/**
2791 * Releases access to the internal data address that was acquired earlier using
2792 * Dart_TypedDataAcquireData.
2793 *
2794 * \param object The typed data object whose internal data address is to be
2795 * released.
2796 *
2797 * \return Success if the internal data address is released successfully.
2798 * Otherwise, returns an error handle.
2799 */
2801
2802/**
2803 * Returns the TypedData object associated with the ByteBuffer object.
2804 *
2805 * \param byte_buffer The ByteBuffer object.
2806 *
2807 * \return The TypedData object if no error occurs. Otherwise returns
2808 * an error handle.
2809 */
2811
2812/*
2813 * ============================================================
2814 * Invoking Constructors, Methods, Closures and Field accessors
2815 * ============================================================
2816 */
2817
2818/**
2819 * Invokes a constructor, creating a new object.
2820 *
2821 * This function allows hidden constructors (constructors with leading
2822 * underscores) to be called.
2823 *
2824 * \param type Type of object to be constructed.
2825 * \param constructor_name The name of the constructor to invoke. Use
2826 * Dart_Null() or Dart_EmptyString() to invoke the unnamed constructor.
2827 * This name should not include the name of the class.
2828 * \param number_of_arguments Size of the arguments array.
2829 * \param arguments An array of arguments to the constructor.
2830 *
2831 * \return If the constructor is called and completes successfully,
2832 * then the new object. If an error occurs during execution, then an
2833 * error handle is returned.
2834 */
2837 Dart_Handle constructor_name,
2838 int number_of_arguments,
2839 Dart_Handle* arguments);
2840
2841/**
2842 * Allocate a new object without invoking a constructor.
2843 *
2844 * \param type The type of an object to be allocated.
2845 *
2846 * \return The new object. If an error occurs during execution, then an
2847 * error handle is returned.
2848 */
2850
2851/**
2852 * Allocate a new object without invoking a constructor, and sets specified
2853 * native fields.
2854 *
2855 * \param type The type of an object to be allocated.
2856 * \param num_native_fields The number of native fields to set.
2857 * \param native_fields An array containing the value of native fields.
2858 *
2859 * \return The new object. If an error occurs during execution, then an
2860 * error handle is returned.
2861 */
2864 intptr_t num_native_fields,
2865 const intptr_t* native_fields);
2866
2867/**
2868 * Invokes a method or function.
2869 *
2870 * The 'target' parameter may be an object, type, or library. If
2871 * 'target' is an object, then this function will invoke an instance
2872 * method. If 'target' is a type, then this function will invoke a
2873 * static method. If 'target' is a library, then this function will
2874 * invoke a top-level function from that library.
2875 * NOTE: This API call cannot be used to invoke methods of a type object.
2876 *
2877 * This function ignores visibility (leading underscores in names).
2878 *
2879 * May generate an unhandled exception error.
2880 *
2881 * \param target An object, type, or library.
2882 * \param name The name of the function or method to invoke.
2883 * \param number_of_arguments Size of the arguments array.
2884 * \param arguments An array of arguments to the function.
2885 *
2886 * \return If the function or method is called and completes
2887 * successfully, then the return value is returned. If an error
2888 * occurs during execution, then an error handle is returned.
2889 */
2893 int number_of_arguments,
2894 Dart_Handle* arguments);
2895/* TODO(turnidge): Document how to invoke operators. */
2896
2897/**
2898 * Invokes a Closure with the given arguments.
2899 *
2900 * May generate an unhandled exception error.
2901 *
2902 * \return If no error occurs during execution, then the result of
2903 * invoking the closure is returned. If an error occurs during
2904 * execution, then an error handle is returned.
2905 */
2908 int number_of_arguments,
2909 Dart_Handle* arguments);
2910
2911/**
2912 * Invokes a Generative Constructor on an object that was previously
2913 * allocated using Dart_Allocate/Dart_AllocateWithNativeFields.
2914 *
2915 * The 'object' parameter must be an object.
2916 *
2917 * This function ignores visibility (leading underscores in names).
2918 *
2919 * May generate an unhandled exception error.
2920 *
2921 * \param object An object.
2922 * \param name The name of the constructor to invoke.
2923 * Use Dart_Null() or Dart_EmptyString() to invoke the unnamed constructor.
2924 * \param number_of_arguments Size of the arguments array.
2925 * \param arguments An array of arguments to the function.
2926 *
2927 * \return If the constructor is called and completes
2928 * successfully, then the object is returned. If an error
2929 * occurs during execution, then an error handle is returned.
2930 */
2934 int number_of_arguments,
2935 Dart_Handle* arguments);
2936
2937/**
2938 * Gets the value of a field.
2939 *
2940 * The 'container' parameter may be an object, type, or library. If
2941 * 'container' is an object, then this function will access an
2942 * instance field. If 'container' is a type, then this function will
2943 * access a static field. If 'container' is a library, then this
2944 * function will access a top-level variable.
2945 * NOTE: This API call cannot be used to access fields of a type object.
2946 *
2947 * This function ignores field visibility (leading underscores in names).
2948 *
2949 * May generate an unhandled exception error.
2950 *
2951 * \param container An object, type, or library.
2952 * \param name A field name.
2953 *
2954 * \return If no error occurs, then the value of the field is
2955 * returned. Otherwise an error handle is returned.
2956 */
2959
2960/**
2961 * Sets the value of a field.
2962 *
2963 * The 'container' parameter may actually be an object, type, or
2964 * library. If 'container' is an object, then this function will
2965 * access an instance field. If 'container' is a type, then this
2966 * function will access a static field. If 'container' is a library,
2967 * then this function will access a top-level variable.
2968 * NOTE: This API call cannot be used to access fields of a type object.
2969 *
2970 * This function ignores field visibility (leading underscores in names).
2971 *
2972 * May generate an unhandled exception error.
2973 *
2974 * \param container An object, type, or library.
2975 * \param name A field name.
2976 * \param value The new field value.
2977 *
2978 * \return A valid handle if no error occurs.
2979 */
2982
2983/*
2984 * ==========
2985 * Exceptions
2986 * ==========
2987 */
2988
2989/*
2990 * TODO(turnidge): Remove these functions from the api and replace all
2991 * uses with Dart_NewUnhandledExceptionError. */
2992
2993/**
2994 * Throws an exception.
2995 *
2996 * This function causes a Dart language exception to be thrown. This
2997 * will proceed in the standard way, walking up Dart frames until an
2998 * appropriate 'catch' block is found, executing 'finally' blocks,
2999 * etc.
3000 *
3001 * If an error handle is passed into this function, the error is
3002 * propagated immediately. See Dart_PropagateError for a discussion
3003 * of error propagation.
3004 *
3005 * If successful, this function does not return. Note that this means
3006 * that the destructors of any stack-allocated C++ objects will not be
3007 * called. If there are no Dart frames on the stack, an error occurs.
3008 *
3009 * \return An error handle if the exception was not thrown.
3010 * Otherwise the function does not return.
3011 */
3013
3014/**
3015 * Rethrows an exception.
3016 *
3017 * Rethrows an exception, unwinding all dart frames on the stack. If
3018 * successful, this function does not return. Note that this means
3019 * that the destructors of any stack-allocated C++ objects will not be
3020 * called. If there are no Dart frames on the stack, an error occurs.
3021 *
3022 * \return An error handle if the exception was not thrown.
3023 * Otherwise the function does not return.
3024 */
3026 Dart_Handle stacktrace);
3027
3028/*
3029 * ===========================
3030 * Native fields and functions
3031 * ===========================
3032 */
3033
3034/**
3035 * Gets the number of native instance fields in an object.
3036 */
3038 int* count);
3039
3040/**
3041 * Gets the value of a native field.
3042 *
3043 * TODO(turnidge): Document.
3044 */
3046 int index,
3047 intptr_t* value);
3048
3049/**
3050 * Sets the value of a native field.
3051 *
3052 * TODO(turnidge): Document.
3053 */
3055 int index,
3056 intptr_t value);
3057
3058/**
3059 * The arguments to a native function.
3060 *
3061 * This object is passed to a native function to represent its
3062 * arguments and return value. It allows access to the arguments to a
3063 * native function by index. It also allows the return value of a
3064 * native function to be set.
3065 */
3066typedef struct _Dart_NativeArguments* Dart_NativeArguments;
3067
3068/**
3069 * Extracts current isolate group data from the native arguments structure.
3070 */
3072
3084
3089
3107
3108enum {
3113};
3114
3115#define BITMASK(size) ((1 << size) - 1)
3116#define DART_NATIVE_ARG_DESCRIPTOR(type, position) \
3117 (((type & BITMASK(kNativeArgTypeSize)) << kNativeArgTypePos) | \
3118 (position & BITMASK(kNativeArgNumberSize)))
3119
3120/**
3121 * Gets the native arguments based on the types passed in and populates
3122 * the passed arguments buffer with appropriate native values.
3123 *
3124 * \param args the Native arguments block passed into the native call.
3125 * \param num_arguments length of argument descriptor array and argument
3126 * values array passed in.
3127 * \param arg_descriptors an array that describes the arguments that
3128 * need to be retrieved. For each argument to be retrieved the descriptor
3129 * contains the argument number (0, 1 etc.) and the argument type
3130 * described using Dart_NativeArgument_Type, e.g:
3131 * DART_NATIVE_ARG_DESCRIPTOR(Dart_NativeArgument_kBool, 1) indicates
3132 * that the first argument is to be retrieved and it should be a boolean.
3133 * \param arg_values array into which the native arguments need to be
3134 * extracted into, the array is allocated by the caller (it could be
3135 * stack allocated to avoid the malloc/free performance overhead).
3136 *
3137 * \return Success if all the arguments could be extracted correctly,
3138 * returns an error handle if there were any errors while extracting the
3139 * arguments (mismatched number of arguments, incorrect types, etc.).
3140 */
3143 int num_arguments,
3144 const Dart_NativeArgument_Descriptor* arg_descriptors,
3145 Dart_NativeArgument_Value* arg_values);
3146
3147/**
3148 * Gets the native argument at some index.
3149 */
3151 int index);
3152/* TODO(turnidge): Specify the behavior of an out-of-bounds access. */
3153
3154/**
3155 * Gets the number of native arguments.
3156 */
3158
3159/**
3160 * Gets all the native fields of the native argument at some index.
3161 * \param args Native arguments structure.
3162 * \param arg_index Index of the desired argument in the structure above.
3163 * \param num_fields size of the intptr_t array 'field_values' passed in.
3164 * \param field_values intptr_t array in which native field values are returned.
3165 * \return Success if the native fields where copied in successfully. Otherwise
3166 * returns an error handle. On success the native field values are copied
3167 * into the 'field_values' array, if the argument at 'arg_index' is a
3168 * null object then 0 is copied as the native field values into the
3169 * 'field_values' array.
3170 */
3173 int arg_index,
3174 int num_fields,
3175 intptr_t* field_values);
3176
3177/**
3178 * Gets the native field of the receiver.
3179 */
3181 intptr_t* value);
3182
3183/**
3184 * Gets a string native argument at some index.
3185 * \param args Native arguments structure.
3186 * \param arg_index Index of the desired argument in the structure above.
3187 * \param peer Returns the peer pointer if the string argument has one.
3188 * \return Success if the string argument has a peer, if it does not
3189 * have a peer then the String object is returned. Otherwise returns
3190 * an error handle (argument is not a String object).
3191 */
3193 int arg_index,
3194 void** peer);
3195
3196/**
3197 * Gets an integer native argument at some index.
3198 * \param args Native arguments structure.
3199 * \param index Index of the desired argument in the structure above.
3200 * \param value Returns the integer value if the argument is an Integer.
3201 * \return Success if no error occurs. Otherwise returns an error handle.
3202 */
3204 int index,
3205 int64_t* value);
3206
3207/**
3208 * Gets a boolean native argument at some index.
3209 * \param args Native arguments structure.
3210 * \param index Index of the desired argument in the structure above.
3211 * \param value Returns the boolean value if the argument is a Boolean.
3212 * \return Success if no error occurs. Otherwise returns an error handle.
3213 */
3215 int index,
3216 bool* value);
3217
3218/**
3219 * Gets a double native argument at some index.
3220 * \param args Native arguments structure.
3221 * \param index Index of the desired argument in the structure above.
3222 * \param value Returns the double value if the argument is a double.
3223 * \return Success if no error occurs. Otherwise returns an error handle.
3224 */
3226 int index,
3227 double* value);
3228
3229/**
3230 * Sets the return value for a native function.
3231 *
3232 * If retval is an Error handle, then error will be propagated once
3233 * the native functions exits. See Dart_PropagateError for a
3234 * discussion of how different types of errors are propagated.
3235 */
3237 Dart_Handle retval);
3238
3241
3243 bool retval);
3244
3246 int64_t retval);
3247
3249 double retval);
3250
3251/**
3252 * A native function.
3253 */
3255
3256/**
3257 * Native entry resolution callback.
3258 *
3259 * For libraries and scripts which have native functions, the embedder
3260 * can provide a native entry resolver. This callback is used to map a
3261 * name/arity to a Dart_NativeFunction. If no function is found, the
3262 * callback should return NULL.
3263 *
3264 * The parameters to the native resolver function are:
3265 * \param name a Dart string which is the name of the native function.
3266 * \param num_of_arguments is the number of arguments expected by the
3267 * native function.
3268 * \param auto_setup_scope is a boolean flag that can be set by the resolver
3269 * to indicate if this function needs a Dart API scope (see Dart_EnterScope/
3270 * Dart_ExitScope) to be setup automatically by the VM before calling into
3271 * the native function. By default most native functions would require this
3272 * to be true but some light weight native functions which do not call back
3273 * into the VM through the Dart API may not require a Dart scope to be
3274 * setup automatically.
3275 *
3276 * \return A valid Dart_NativeFunction which resolves to a native entry point
3277 * for the native function.
3278 *
3279 * See Dart_SetNativeResolver.
3280 */
3282 int num_of_arguments,
3283 bool* auto_setup_scope);
3284/* TODO(turnidge): Consider renaming to NativeFunctionResolver or
3285 * NativeResolver. */
3286
3287/**
3288 * Native entry symbol lookup callback.
3289 *
3290 * For libraries and scripts which have native functions, the embedder
3291 * can provide a callback for mapping a native entry to a symbol. This callback
3292 * maps a native function entry PC to the native function name. If no native
3293 * entry symbol can be found, the callback should return NULL.
3294 *
3295 * The parameters to the native reverse resolver function are:
3296 * \param nf A Dart_NativeFunction.
3297 *
3298 * \return A const UTF-8 string containing the symbol name or NULL.
3299 *
3300 * See Dart_SetNativeResolver.
3301 */
3302typedef const uint8_t* (*Dart_NativeEntrySymbol)(Dart_NativeFunction nf);
3303
3304/**
3305 * FFI Native C function pointer resolver callback.
3306 *
3307 * See Dart_SetFfiNativeResolver.
3308 */
3309typedef void* (*Dart_FfiNativeResolver)(const char* name, uintptr_t args_n);
3310
3311/*
3312 * ===========
3313 * Environment
3314 * ===========
3315 */
3316
3317/**
3318 * An environment lookup callback function.
3319 *
3320 * \param name The name of the value to lookup in the environment.
3321 *
3322 * \return A valid handle to a string if the name exists in the
3323 * current environment or Dart_Null() if not.
3324 */
3326
3327/**
3328 * Sets the environment callback for the current isolate. This
3329 * callback is used to lookup environment values by name in the
3330 * current environment. This enables the embedder to supply values for
3331 * the const constructors bool.fromEnvironment, int.fromEnvironment
3332 * and String.fromEnvironment.
3333 */
3336
3337/**
3338 * Sets the callback used to resolve native functions for a library.
3339 *
3340 * \param library A library.
3341 * \param resolver A native entry resolver.
3342 *
3343 * \return A valid handle if the native resolver was set successfully.
3344 */
3347 Dart_NativeEntryResolver resolver,
3348 Dart_NativeEntrySymbol symbol);
3349/* TODO(turnidge): Rename to Dart_LibrarySetNativeResolver? */
3350
3351/**
3352 * Returns the callback used to resolve native functions for a library.
3353 *
3354 * \param library A library.
3355 * \param resolver a pointer to a Dart_NativeEntryResolver
3356 *
3357 * \return A valid handle if the library was found.
3358 */
3361
3362/**
3363 * Returns the callback used to resolve native function symbols for a library.
3364 *
3365 * \param library A library.
3366 * \param resolver a pointer to a Dart_NativeEntrySymbol.
3367 *
3368 * \return A valid handle if the library was found.
3369 */
3371 Dart_NativeEntrySymbol* resolver);
3372
3373/**
3374 * Sets the callback used to resolve FFI native functions for a library.
3375 * The resolved functions are expected to be a C function pointer of the
3376 * correct signature (as specified in the `@Native<NFT>()` function
3377 * annotation in Dart code).
3378 *
3379 * NOTE: This is an experimental feature and might change in the future.
3380 *
3381 * \param library A library.
3382 * \param resolver A native function resolver.
3383 *
3384 * \return A valid handle if the native resolver was set successfully.
3385 */
3388
3389/*
3390 * =====================
3391 * Scripts and Libraries
3392 * =====================
3393 */
3394
3400
3401/**
3402 * The library tag handler is a multi-purpose callback provided by the
3403 * embedder to the Dart VM. The embedder implements the tag handler to
3404 * provide the ability to load Dart scripts and imports.
3405 *
3406 * -- TAGS --
3407 *
3408 * Dart_kCanonicalizeUrl
3409 *
3410 * This tag indicates that the embedder should canonicalize 'url' with
3411 * respect to 'library'. For most embedders, the
3412 * Dart_DefaultCanonicalizeUrl function is a sufficient implementation
3413 * of this tag. The return value should be a string holding the
3414 * canonicalized url.
3415 *
3416 * Dart_kImportTag
3417 *
3418 * This tag is used to load a library from IsolateMirror.loadUri. The embedder
3419 * should call Dart_LoadLibraryFromKernel to provide the library to the VM. The
3420 * return value should be an error or library (the result from
3421 * Dart_LoadLibraryFromKernel).
3422 *
3423 * Dart_kKernelTag
3424 *
3425 * This tag is used to load the intermediate file (kernel) generated by
3426 * the Dart front end. This tag is typically used when a 'hot-reload'
3427 * of an application is needed and the VM is 'use dart front end' mode.
3428 * The dart front end typically compiles all the scripts, imports and part
3429 * files into one intermediate file hence we don't use the source/import or
3430 * script tags. The return value should be an error or a TypedData containing
3431 * the kernel bytes.
3432 *
3433 */
3435 Dart_LibraryTag tag,
3436 Dart_Handle library_or_package_map_url,
3437 Dart_Handle url);
3438
3439/**
3440 * Sets library tag handler for the current isolate. This handler is
3441 * used to handle the various tags encountered while loading libraries
3442 * or scripts in the isolate.
3443 *
3444 * \param handler Handler code to be used for handling the various tags
3445 * encountered while loading libraries or scripts in the isolate.
3446 *
3447 * \return If no error occurs, the handler is set for the isolate.
3448 * Otherwise an error handle is returned.
3449 *
3450 * TODO(turnidge): Document.
3451 */
3454
3455/**
3456 * Handles deferred loading requests. When this handler is invoked, it should
3457 * eventually load the deferred loading unit with the given id and call
3458 * Dart_DeferredLoadComplete or Dart_DeferredLoadCompleteError. It is
3459 * recommended that the loading occur asynchronously, but it is permitted to
3460 * call Dart_DeferredLoadComplete or Dart_DeferredLoadCompleteError before the
3461 * handler returns.
3462 *
3463 * If an error is returned, it will be propagated through
3464 * `prefix.loadLibrary()`. This is useful for synchronous
3465 * implementations, which must propagate any unwind errors from
3466 * Dart_DeferredLoadComplete or Dart_DeferredLoadComplete. Otherwise the handler
3467 * should return a non-error such as `Dart_Null()`.
3468 */
3469typedef Dart_Handle (*Dart_DeferredLoadHandler)(intptr_t loading_unit_id);
3470
3471/**
3472 * Sets the deferred load handler for the current isolate. This handler is
3473 * used to handle loading deferred imports in an AppJIT or AppAOT program.
3474 */
3477
3478/**
3479 * Notifies the VM that a deferred load completed successfully. This function
3480 * will eventually cause the corresponding `prefix.loadLibrary()` futures to
3481 * complete.
3482 *
3483 * Requires the current isolate to be the same current isolate during the
3484 * invocation of the Dart_DeferredLoadHandler.
3485 */
3487Dart_DeferredLoadComplete(intptr_t loading_unit_id,
3488 const uint8_t* snapshot_data,
3489 const uint8_t* snapshot_instructions);
3490
3491/**
3492 * Notifies the VM that a deferred load failed. This function
3493 * will eventually cause the corresponding `prefix.loadLibrary()` futures to
3494 * complete with an error.
3495 *
3496 * If `transient` is true, future invocations of `prefix.loadLibrary()` will
3497 * trigger new load requests. If false, futures invocation will complete with
3498 * the same error.
3499 *
3500 * Requires the current isolate to be the same current isolate during the
3501 * invocation of the Dart_DeferredLoadHandler.
3502 */
3504Dart_DeferredLoadCompleteError(intptr_t loading_unit_id,
3505 const char* error_message,
3506 bool transient);
3507
3508/**
3509 * Canonicalizes a url with respect to some library.
3510 *
3511 * The url is resolved with respect to the library's url and some url
3512 * normalizations are performed.
3513 *
3514 * This canonicalization function should be sufficient for most
3515 * embedders to implement the Dart_kCanonicalizeUrl tag.
3516 *
3517 * \param base_url The base url relative to which the url is
3518 * being resolved.
3519 * \param url The url being resolved and canonicalized. This
3520 * parameter is a string handle.
3521 *
3522 * \return If no error occurs, a String object is returned. Otherwise
3523 * an error handle is returned.
3524 */
3526 Dart_Handle url);
3527
3528/**
3529 * Loads the root library for the current isolate.
3530 *
3531 * Requires there to be no current root library.
3532 *
3533 * \param kernel_buffer A buffer which contains a kernel binary (see
3534 * pkg/kernel/binary.md). Must remain valid until isolate group shutdown.
3535 * \param kernel_size Length of the passed in buffer.
3536 *
3537 * \return A handle to the root library, or an error.
3538 */
3540Dart_LoadScriptFromKernel(const uint8_t* kernel_buffer, intptr_t kernel_size);
3541
3542/**
3543 * Gets the library for the root script for the current isolate.
3544 *
3545 * If the root script has not yet been set for the current isolate,
3546 * this function returns Dart_Null(). This function never returns an
3547 * error handle.
3548 *
3549 * \return Returns the root Library for the current isolate or Dart_Null().
3550 */
3552
3553/**
3554 * Sets the root library for the current isolate.
3555 *
3556 * \return Returns an error handle if `library` is not a library handle.
3557 */
3559
3560/**
3561 * Lookup or instantiate a legacy type by name and type arguments from a
3562 * Library.
3563 *
3564 * \param library The library containing the class or interface.
3565 * \param class_name The class name for the type.
3566 * \param number_of_type_arguments Number of type arguments.
3567 * For non parametric types the number of type arguments would be 0.
3568 * \param type_arguments Pointer to an array of type arguments.
3569 * For non parametric types a NULL would be passed in for this argument.
3570 *
3571 * \return If no error occurs, the type is returned.
3572 * Otherwise an error handle is returned.
3573 */
3575 Dart_Handle class_name,
3576 intptr_t number_of_type_arguments,
3577 Dart_Handle* type_arguments);
3578
3579/**
3580 * Lookup or instantiate a nullable type by name and type arguments from
3581 * Library.
3582 *
3583 * \param library The library containing the class or interface.
3584 * \param class_name The class name for the type.
3585 * \param number_of_type_arguments Number of type arguments.
3586 * For non parametric types the number of type arguments would be 0.
3587 * \param type_arguments Pointer to an array of type arguments.
3588 * For non parametric types a NULL would be passed in for this argument.
3589 *
3590 * \return If no error occurs, the type is returned.
3591 * Otherwise an error handle is returned.
3592 */
3594 Dart_Handle class_name,
3595 intptr_t number_of_type_arguments,
3596 Dart_Handle* type_arguments);
3597
3598/**
3599 * Lookup or instantiate a non-nullable type by name and type arguments from
3600 * Library.
3601 *
3602 * \param library The library containing the class or interface.
3603 * \param class_name The class name for the type.
3604 * \param number_of_type_arguments Number of type arguments.
3605 * For non parametric types the number of type arguments would be 0.
3606 * \param type_arguments Pointer to an array of type arguments.
3607 * For non parametric types a NULL would be passed in for this argument.
3608 *
3609 * \return If no error occurs, the type is returned.
3610 * Otherwise an error handle is returned.
3611 */
3614 Dart_Handle class_name,
3615 intptr_t number_of_type_arguments,
3616 Dart_Handle* type_arguments);
3617
3618/**
3619 * Creates a nullable version of the provided type.
3620 *
3621 * \param type The type to be converted to a nullable type.
3622 *
3623 * \return If no error occurs, a nullable type is returned.
3624 * Otherwise an error handle is returned.
3625 */
3627
3628/**
3629 * Creates a non-nullable version of the provided type.
3630 *
3631 * \param type The type to be converted to a non-nullable type.
3632 *
3633 * \return If no error occurs, a non-nullable type is returned.
3634 * Otherwise an error handle is returned.
3635 */
3637
3638/**
3639 * A type's nullability.
3640 *
3641 * \param type A Dart type.
3642 * \param result An out parameter containing the result of the check. True if
3643 * the type is of the specified nullability, false otherwise.
3644 *
3645 * \return Returns an error handle if type is not of type Type.
3646 */
3650
3651/**
3652 * Lookup a class or interface by name from a Library.
3653 *
3654 * \param library The library containing the class or interface.
3655 * \param class_name The name of the class or interface.
3656 *
3657 * \return If no error occurs, the class or interface is
3658 * returned. Otherwise an error handle is returned.
3659 */
3661 Dart_Handle class_name);
3662/* TODO(asiva): The above method needs to be removed once all uses
3663 * of it are removed from the embedder code. */
3664
3665/**
3666 * Returns an import path to a Library, such as "file:///test.dart" or
3667 * "dart:core".
3668 */
3670
3671/**
3672 * Returns a URL from which a Library was loaded.
3673 */
3675
3676/**
3677 * \return An array of libraries.
3678 */
3680
3682/* TODO(turnidge): Consider returning Dart_Null() when the library is
3683 * not found to distinguish that from a true error case. */
3684
3685/**
3686 * Report an loading error for the library.
3687 *
3688 * \param library The library that failed to load.
3689 * \param error The Dart error instance containing the load error.
3690 *
3691 * \return If the VM handles the error, the return value is
3692 * a null handle. If it doesn't handle the error, the error
3693 * object is returned.
3694 */
3697
3698/**
3699 * Called by the embedder to load a partial program. Does not set the root
3700 * library.
3701 *
3702 * \param kernel_buffer A buffer which contains a kernel binary (see
3703 * pkg/kernel/binary.md). Must remain valid until isolate shutdown.
3704 * \param kernel_buffer_size Length of the passed in buffer.
3705 *
3706 * \return A handle to the main library of the compilation unit, or an error.
3707 */
3709Dart_LoadLibraryFromKernel(const uint8_t* kernel_buffer,
3710 intptr_t kernel_buffer_size);
3713
3714/**
3715 * Indicates that all outstanding load requests have been satisfied.
3716 * This finalizes all the new classes loaded and optionally completes
3717 * deferred library futures.
3718 *
3719 * Requires there to be a current isolate.
3720 *
3721 * \param complete_futures Specify true if all deferred library
3722 * futures should be completed, false otherwise.
3723 *
3724 * \return Success if all classes have been finalized and deferred library
3725 * futures are completed. Otherwise, returns an error.
3726 */
3728Dart_FinalizeLoading(bool complete_futures);
3729
3730/*
3731 * =====
3732 * Peers
3733 * =====
3734 */
3735
3736/**
3737 * The peer field is a lazily allocated field intended for storage of
3738 * an uncommonly used values. Most instances types can have a peer
3739 * field allocated. The exceptions are subtypes of Null, num, and
3740 * bool.
3741 */
3742
3743/**
3744 * Returns the value of peer field of 'object' in 'peer'.
3745 *
3746 * \param object An object.
3747 * \param peer An out parameter that returns the value of the peer
3748 * field.
3749 *
3750 * \return Returns an error if 'object' is a subtype of Null, num, or
3751 * bool.
3752 */
3754
3755/**
3756 * Sets the value of the peer field of 'object' to the value of
3757 * 'peer'.
3758 *
3759 * \param object An object.
3760 * \param peer A value to store in the peer field.
3761 *
3762 * \return Returns an error if 'object' is a subtype of Null, num, or
3763 * bool.
3764 */
3766
3767/*
3768 * ======
3769 * Kernel
3770 * ======
3771 */
3772
3773/**
3774 * Experimental support for Dart to Kernel parser isolate.
3775 *
3776 * TODO(hausner): Document finalized interface.
3777 *
3778 */
3779
3780// TODO(33433): Remove kernel service from the embedding API.
3781
3789
3796
3803
3807
3808/**
3809 * Compiles the given `script_uri` to a kernel file.
3810 *
3811 * \param platform_kernel A buffer containing the kernel of the platform (e.g.
3812 * `vm_platform_strong.dill`). The VM does not take ownership of this memory.
3813 *
3814 * \param platform_kernel_size The length of the platform_kernel buffer.
3815 *
3816 * \param snapshot_compile Set to `true` when the compilation is for a snapshot.
3817 * This is used by the frontend to determine if compilation related information
3818 * should be printed to console (e.g., null safety mode).
3819 *
3820 * \param embed_sources Set to `true` when sources should be embedded in the
3821 * kernel file.
3822 *
3823 * \param verbosity Specifies the logging behavior of the kernel compilation
3824 * service.
3825 *
3826 * \return Returns the result of the compilation.
3827 *
3828 * On a successful compilation the returned [Dart_KernelCompilationResult] has
3829 * a status of [Dart_KernelCompilationStatus_Ok] and the `kernel`/`kernel_size`
3830 * fields are set. The caller takes ownership of the malloc()ed buffer.
3831 *
3832 * On a failed compilation the `error` might be set describing the reason for
3833 * the failed compilation. The caller takes ownership of the malloc()ed
3834 * error.
3835 *
3836 * Requires there to be a current isolate.
3837 */
3839Dart_CompileToKernel(const char* script_uri,
3840 const uint8_t* platform_kernel,
3841 const intptr_t platform_kernel_size,
3842 bool incremental_compile,
3843 bool snapshot_compile,
3844 bool embed_sources,
3845 const char* package_config,
3847
3848typedef struct {
3849 const char* uri;
3850 const char* source;
3852
3854
3855/**
3856 * Sets the kernel buffer which will be used to load Dart SDK sources
3857 * dynamically at runtime.
3858 *
3859 * \param platform_kernel A buffer containing kernel which has sources for the
3860 * Dart SDK populated. Note: The VM does not take ownership of this memory.
3861 *
3862 * \param platform_kernel_size The length of the platform_kernel buffer.
3863 */
3865 const uint8_t* platform_kernel,
3866 const intptr_t platform_kernel_size);
3867
3868/**
3869 * Detect the null safety opt-in status.
3870 *
3871 * When running from source, it is based on the opt-in status of `script_uri`.
3872 * When running from a kernel buffer, it is based on the mode used when
3873 * generating `kernel_buffer`.
3874 * When running from an appJIT or AOT snapshot, it is based on the mode used
3875 * when generating `snapshot_data`.
3876 *
3877 * \param script_uri Uri of the script that contains the source code
3878 *
3879 * \param package_config Uri of the package configuration file (either in format
3880 * of .packages or .dart_tool/package_config.json) for the null safety
3881 * detection to resolve package imports against. If this parameter is not
3882 * passed the package resolution of the parent isolate should be used.
3883 *
3884 * \param original_working_directory current working directory when the VM
3885 * process was launched, this is used to correctly resolve the path specified
3886 * for package_config.
3887 *
3888 * \param snapshot_data Buffer containing the snapshot data of the
3889 * isolate or NULL if no snapshot is provided. If provided, the buffers must
3890 * remain valid until the isolate shuts down.
3891 *
3892 * \param snapshot_instructions Buffer containing the snapshot instructions of
3893 * the isolate or NULL if no snapshot is provided. If provided, the buffers
3894 * must remain valid until the isolate shuts down.
3895 *
3896 * \param kernel_buffer A buffer which contains a kernel/DIL program. Must
3897 * remain valid until isolate shutdown.
3898 *
3899 * \param kernel_buffer_size The size of `kernel_buffer`.
3900 *
3901 * \return Returns true if the null safety is opted in by the input being
3902 * run `script_uri`, `snapshot_data` or `kernel_buffer`.
3903 *
3904 */
3905DART_EXPORT bool Dart_DetectNullSafety(const char* script_uri,
3906 const char* package_config,
3907 const char* original_working_directory,
3908 const uint8_t* snapshot_data,
3909 const uint8_t* snapshot_instructions,
3910 const uint8_t* kernel_buffer,
3911 intptr_t kernel_buffer_size);
3912
3913#define DART_KERNEL_ISOLATE_NAME "kernel-service"
3914
3915/*
3916 * =======
3917 * Service
3918 * =======
3919 */
3920
3921#define DART_VM_SERVICE_ISOLATE_NAME "vm-service"
3922
3923/**
3924 * Returns true if isolate is the service isolate.
3925 *
3926 * \param isolate An isolate
3927 *
3928 * \return Returns true if 'isolate' is the service isolate.
3929 */
3931
3932/**
3933 * Writes the CPU profile to the timeline as a series of 'instant' events.
3934 *
3935 * Note that this is an expensive operation.
3936 *
3937 * \param main_port The main port of the Isolate whose profile samples to write.
3938 * \param error An optional error, must be free()ed by caller.
3939 *
3940 * \return Returns true if the profile is successfully written and false
3941 * otherwise.
3942 */
3944
3945/*
3946 * ==============
3947 * Precompilation
3948 * ==============
3949 */
3950
3951/**
3952 * Compiles all functions reachable from entry points and marks
3953 * the isolate to disallow future compilation.
3954 *
3955 * Entry points should be specified using `@pragma("vm:entry-point")`
3956 * annotation.
3957 *
3958 * \return An error handle if a compilation error or runtime error running const
3959 * constructors was encountered.
3960 */
3962
3964 void* callback_data,
3965 intptr_t loading_unit_id,
3966 void** write_callback_data,
3967 void** write_debug_callback_data);
3968typedef void (*Dart_StreamingWriteCallback)(void* callback_data,
3969 const uint8_t* buffer,
3970 intptr_t size);
3971typedef void (*Dart_StreamingCloseCallback)(void* callback_data);
3972
3974
3975// On Darwin systems, 'dlsym' adds an '_' to the beginning of the symbol name.
3976// Use the '...CSymbol' definitions for resolving through 'dlsym'. The actual
3977// symbol names in the objects are given by the '...AsmSymbol' definitions.
3978#if defined(__APPLE__)
3979#define kSnapshotBuildIdCSymbol "kDartSnapshotBuildId"
3980#define kVmSnapshotDataCSymbol "kDartVmSnapshotData"
3981#define kVmSnapshotInstructionsCSymbol "kDartVmSnapshotInstructions"
3982#define kVmSnapshotBssCSymbol "kDartVmSnapshotBss"
3983#define kIsolateSnapshotDataCSymbol "kDartIsolateSnapshotData"
3984#define kIsolateSnapshotInstructionsCSymbol "kDartIsolateSnapshotInstructions"
3985#define kIsolateSnapshotBssCSymbol "kDartIsolateSnapshotBss"
3986#else
3987#define kSnapshotBuildIdCSymbol "_kDartSnapshotBuildId"
3988#define kVmSnapshotDataCSymbol "_kDartVmSnapshotData"
3989#define kVmSnapshotInstructionsCSymbol "_kDartVmSnapshotInstructions"
3990#define kVmSnapshotBssCSymbol "_kDartVmSnapshotBss"
3991#define kIsolateSnapshotDataCSymbol "_kDartIsolateSnapshotData"
3992#define kIsolateSnapshotInstructionsCSymbol "_kDartIsolateSnapshotInstructions"
3993#define kIsolateSnapshotBssCSymbol "_kDartIsolateSnapshotBss"
3994#endif
3995
3996#define kSnapshotBuildIdAsmSymbol "_kDartSnapshotBuildId"
3997#define kVmSnapshotDataAsmSymbol "_kDartVmSnapshotData"
3998#define kVmSnapshotInstructionsAsmSymbol "_kDartVmSnapshotInstructions"
3999#define kVmSnapshotBssAsmSymbol "_kDartVmSnapshotBss"
4000#define kIsolateSnapshotDataAsmSymbol "_kDartIsolateSnapshotData"
4001#define kIsolateSnapshotInstructionsAsmSymbol \
4002 "_kDartIsolateSnapshotInstructions"
4003#define kIsolateSnapshotBssAsmSymbol "_kDartIsolateSnapshotBss"
4004
4005/**
4006 * Creates a precompiled snapshot.
4007 * - A root library must have been loaded.
4008 * - Dart_Precompile must have been called.
4009 *
4010 * Outputs an assembly file defining the symbols listed in the definitions
4011 * above.
4012 *
4013 * The assembly should be compiled as a static or shared library and linked or
4014 * loaded by the embedder. Running this snapshot requires a VM compiled with
4015 * DART_PRECOMPILED_SNAPSHOT. The kDartVmSnapshotData and
4016 * kDartVmSnapshotInstructions should be passed to Dart_Initialize. The
4017 * kDartIsolateSnapshotData and kDartIsolateSnapshotInstructions should be
4018 * passed to Dart_CreateIsolateGroup.
4019 *
4020 * The callback will be invoked one or more times to provide the assembly code.
4021 *
4022 * If stripped is true, then the assembly code will not include DWARF
4023 * debugging sections.
4024 *
4025 * If debug_callback_data is provided, debug_callback_data will be used with
4026 * the callback to provide separate debugging information.
4027 *
4028 * \return A valid handle if no error occurs during the operation.
4029 */
4032 void* callback_data,
4033 bool stripped,
4034 void* debug_callback_data);
4037 Dart_CreateLoadingUnitCallback next_callback,
4038 void* next_callback_data,
4039 bool stripped,
4040 Dart_StreamingWriteCallback write_callback,
4041 Dart_StreamingCloseCallback close_callback);
4042
4043/**
4044 * Creates a precompiled snapshot.
4045 * - A root library must have been loaded.
4046 * - Dart_Precompile must have been called.
4047 *
4048 * Outputs an ELF shared library defining the symbols
4049 * - _kDartVmSnapshotData
4050 * - _kDartVmSnapshotInstructions
4051 * - _kDartIsolateSnapshotData
4052 * - _kDartIsolateSnapshotInstructions
4053 *
4054 * The shared library should be dynamically loaded by the embedder.
4055 * Running this snapshot requires a VM compiled with DART_PRECOMPILED_SNAPSHOT.
4056 * The kDartVmSnapshotData and kDartVmSnapshotInstructions should be passed to
4057 * Dart_Initialize. The kDartIsolateSnapshotData and
4058 * kDartIsolateSnapshotInstructions should be passed to Dart_CreateIsolate.
4059 *
4060 * The callback will be invoked one or more times to provide the binary output.
4061 *
4062 * If stripped is true, then the binary output will not include DWARF
4063 * debugging sections.
4064 *
4065 * If debug_callback_data is provided, debug_callback_data will be used with
4066 * the callback to provide separate debugging information.
4067 *
4068 * \return A valid handle if no error occurs during the operation.
4069 */
4072 void* callback_data,
4073 bool stripped,
4074 void* debug_callback_data);
4077 void* next_callback_data,
4078 bool stripped,
4079 Dart_StreamingWriteCallback write_callback,
4080 Dart_StreamingCloseCallback close_callback);
4081
4082/**
4083 * Like Dart_CreateAppAOTSnapshotAsAssembly, but only includes
4084 * kDartVmSnapshotData and kDartVmSnapshotInstructions. It also does
4085 * not strip DWARF information from the generated assembly or allow for
4086 * separate debug information.
4087 */
4090 void* callback_data);
4091
4092/**
4093 * Sorts the class-ids in depth first traversal order of the inheritance
4094 * tree. This is a costly operation, but it can make method dispatch
4095 * more efficient and is done before writing snapshots.
4096 *
4097 * \return A valid handle if no error occurs during the operation.
4098 */
4100
4101/**
4102 * Creates a snapshot that caches compiled code and type feedback for faster
4103 * startup and quicker warmup in a subsequent process.
4104 *
4105 * Outputs a snapshot in two pieces. The pieces should be passed to
4106 * Dart_CreateIsolateGroup in a VM using the same VM snapshot pieces used in the
4107 * current VM. The instructions piece must be loaded with read and execute
4108 * permissions; the data piece may be loaded as read-only.
4109 *
4110 * - Requires the VM to have not been started with --precompilation.
4111 * - Not supported when targeting IA32.
4112 * - The VM writing the snapshot and the VM reading the snapshot must be the
4113 * same version, must be built in the same DEBUG/RELEASE/PRODUCT mode, must
4114 * be targeting the same architecture, and must both be in checked mode or
4115 * both in unchecked mode.
4116 *
4117 * The buffers are scope allocated and are only valid until the next call to
4118 * Dart_ExitScope.
4119 *
4120 * \return A valid handle if no error occurs during the operation.
4121 */
4123Dart_CreateAppJITSnapshotAsBlobs(uint8_t** isolate_snapshot_data_buffer,
4124 intptr_t* isolate_snapshot_data_size,
4125 uint8_t** isolate_snapshot_instructions_buffer,
4126 intptr_t* isolate_snapshot_instructions_size);
4127
4128/**
4129 * Get obfuscation map for precompiled code.
4130 *
4131 * Obfuscation map is encoded as a JSON array of pairs (original name,
4132 * obfuscated name).
4133 *
4134 * \return Returns an error handler if the VM was built in a mode that does not
4135 * support obfuscation.
4136 */
4138Dart_GetObfuscationMap(uint8_t** buffer, intptr_t* buffer_length);
4139
4140/**
4141 * Returns whether the VM only supports running from precompiled snapshots and
4142 * not from any other kind of snapshot or from source (that is, the VM was
4143 * compiled with DART_PRECOMPILED_RUNTIME).
4144 */
4146
4147/**
4148 * Print a native stack trace. Used for crash handling.
4149 *
4150 * If context is NULL, prints the current stack trace. Otherwise, context
4151 * should be a CONTEXT* (Windows) or ucontext_t* (POSIX) from a signal handler
4152 * running on the current thread.
4153 */
4155
4156/**
4157 * Indicate that the process is about to abort, and the Dart VM should not
4158 * attempt to cleanup resources.
4159 */
4161
4162/**
4163 * Callback provided by the embedder that is used by the VM to
4164 * produce footnotes appended to DWARF stack traces.
4165 *
4166 * Whenever VM formats a stack trace as a string it would call this callback
4167 * passing raw program counters for each frame in the stack trace.
4168 *
4169 * Embedder can then return a string which if not-null will be appended to the
4170 * formatted stack trace.
4171 *
4172 * Returned string is expected to be `malloc()` allocated. VM takes ownership
4173 * of the returned string and will `free()` it.
4174 *
4175 * \param addresses raw program counter addresses for each frame
4176 * \param count number of elements in the addresses array
4177 */
4178typedef char* (*Dart_DwarfStackTraceFootnoteCallback)(void* addresses[],
4179 intptr_t count);
4180
4181/**
4182 * Configure DWARF stack trace footnote callback.
4183 */
4186
4187#endif /* INCLUDE_DART_API_H_ */ /* NOLINT */
int count
static uint32_t buffer_size(uint32_t offset, uint32_t maxAlignment)
static bool equal(const SkBitmap &a, const SkBitmap &b)
DART_EXPORT void Dart_SetPausedOnExit(bool paused)
DART_EXPORT Dart_Handle Dart_ListSetAsBytes(Dart_Handle list, intptr_t offset, const uint8_t *native_array, intptr_t length)
DART_EXPORT Dart_Isolate Dart_CreateIsolateGroup(const char *script_uri, const char *name, const uint8_t *isolate_snapshot_data, const uint8_t *isolate_snapshot_instructions, Dart_IsolateFlags *flags, void *isolate_group_data, void *isolate_data, char **error)
DART_EXPORT Dart_Handle Dart_HandleFromPersistent(Dart_PersistentHandle object)
DART_EXPORT Dart_Handle Dart_StringToUTF16(Dart_Handle str, uint16_t *utf16_array, intptr_t *length)
DART_EXPORT Dart_Handle Dart_StringLength(Dart_Handle str, intptr_t *length)
DART_EXPORT void Dart_IsolateFlagsInitialize(Dart_IsolateFlags *flags)
DART_EXPORT bool Dart_IsInteger(Dart_Handle object)
DART_EXPORT Dart_Handle Dart_TypeNever(void)
DART_EXPORT void * Dart_CurrentIsolateData(void)
DART_EXPORT Dart_Handle Dart_FunctionIsStatic(Dart_Handle function, bool *is_static)
DART_EXPORT Dart_TypedData_Type Dart_GetTypeOfExternalTypedData(Dart_Handle object)
Dart_CoreType_Id
Definition dart_api.h:2479
@ Dart_CoreType_Dynamic
Definition dart_api.h:2480
@ Dart_CoreType_Int
Definition dart_api.h:2481
@ Dart_CoreType_String
Definition dart_api.h:2482
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_CreateAppAOTSnapshotAsElf(Dart_StreamingWriteCallback callback, void *callback_data, bool stripped, void *debug_callback_data)
void(* Dart_UnregisterKernelBlobCallback)(const char *kernel_blob_uri)
Definition dart_api.h:894
DART_EXPORT Dart_Handle Dart_NewDouble(double value)
DART_EXPORT void Dart_SetIntegerReturnValue(Dart_NativeArguments args, int64_t retval)
DART_EXPORT Dart_Handle Dart_GetNonNullableType(Dart_Handle library, Dart_Handle class_name, intptr_t number_of_type_arguments, Dart_Handle *type_arguments)
DART_EXPORT Dart_Handle Dart_GetType(Dart_Handle library, Dart_Handle class_name, intptr_t number_of_type_arguments, Dart_Handle *type_arguments)
DART_EXPORT Dart_Port Dart_KernelPort(void)
DART_EXPORT void Dart_DisableHeapSampling(void)
DART_EXPORT void Dart_SetPausedOnStart(bool paused)
Dart_Handle(* Dart_EnvironmentCallback)(Dart_Handle name)
Definition dart_api.h:3325
DART_EXPORT Dart_Handle Dart_SetFfiNativeResolver(Dart_Handle library, Dart_FfiNativeResolver resolver)
void(* Dart_StreamingWriteCallback)(void *callback_data, const uint8_t *buffer, intptr_t size)
Definition dart_api.h:3968
DART_EXPORT void Dart_StartProfiling(void)
DART_EXPORT Dart_FinalizableHandle Dart_NewFinalizableHandle(Dart_Handle object, void *peer, intptr_t external_allocation_size, Dart_HandleFinalizer callback)
DART_EXPORT DART_WARN_UNUSED_RESULT char * Dart_IsolateMakeRunnable(Dart_Isolate isolate)
DART_EXPORT void Dart_PrepareToAbort(void)
void(* Dart_FileWriteCallback)(const void *data, intptr_t length, void *stream)
Definition dart_api.h:807
Dart_Isolate(* Dart_IsolateGroupCreateCallback)(const char *script_uri, const char *main, const char *package_root, const char *package_config, Dart_IsolateFlags *flags, void *isolate_data, char **error)
Definition dart_api.h:654
DART_EXPORT Dart_Handle Dart_SetNativeResolver(Dart_Handle library, Dart_NativeEntryResolver resolver, Dart_NativeEntrySymbol symbol)
DART_EXPORT Dart_Handle Dart_IsNullableType(Dart_Handle type, bool *result)
Dart_KernelCompilationStatus
Definition dart_api.h:3782
@ Dart_KernelCompilationStatus_MsgFailed
Definition dart_api.h:3787
@ Dart_KernelCompilationStatus_Error
Definition dart_api.h:3785
@ Dart_KernelCompilationStatus_Crash
Definition dart_api.h:3786
@ Dart_KernelCompilationStatus_Unknown
Definition dart_api.h:3783
@ Dart_KernelCompilationStatus_Ok
Definition dart_api.h:3784
DART_EXPORT Dart_Handle Dart_ListGetRange(Dart_Handle list, intptr_t offset, intptr_t length, Dart_Handle *result)
DART_EXPORT Dart_Handle Dart_GetNativeResolver(Dart_Handle library, Dart_NativeEntryResolver *resolver)
DART_EXPORT Dart_Handle Dart_NewStringFromUTF8(const uint8_t *utf8_array, intptr_t length)
DART_EXPORT void Dart_ThreadDisableProfiling(void)
DART_EXPORT void Dart_StopProfiling(void)
DART_EXPORT bool Dart_IsBoolean(Dart_Handle object)
void(* Dart_IsolateCleanupCallback)(void *isolate_group_data, void *isolate_data)
Definition dart_api.h:729
DART_EXPORT Dart_Handle Dart_FunctionOwner(Dart_Handle function)
DART_EXPORT bool Dart_WriteProfileToTimeline(Dart_Port main_port, char **error)
DART_EXPORT bool Dart_HandleServiceMessages(void)
DART_EXPORT void Dart_EnterScope(void)
void(* Dart_FileCloseCallback)(void *stream)
Definition dart_api.h:820
DART_EXPORT void Dart_ExitScope(void)
DART_EXPORT Dart_Handle Dart_NewSendPort(Dart_Port port_id)
DART_EXPORT Dart_Handle Dart_TypeVoid(void)
DART_EXPORT bool Dart_IsInstance(Dart_Handle object)
DART_EXPORT Dart_Handle Dart_IntegerToInt64(Dart_Handle integer, int64_t *value)
DART_EXPORT bool Dart_IsStringLatin1(Dart_Handle object)
DART_EXPORT bool Dart_IsNumber(Dart_Handle object)
DART_EXPORT Dart_KernelCompilationResult Dart_KernelListDependencies(void)
DART_EXPORT Dart_Handle Dart_NewExternalTypedData(Dart_TypedData_Type type, void *data, intptr_t length)
Dart_PerformanceMode
Definition dart_api.h:1370
@ Dart_PerformanceMode_Default
Definition dart_api.h:1374
@ Dart_PerformanceMode_Latency
Definition dart_api.h:1381
@ Dart_PerformanceMode_Memory
Definition dart_api.h:1391
@ Dart_PerformanceMode_Throughput
Definition dart_api.h:1386
DART_EXPORT void Dart_DumpNativeStackTrace(void *context)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_Allocate(Dart_Handle type)
DART_EXPORT const char * Dart_VersionString(void)
DART_EXPORT bool Dart_HasServiceMessages(void)
DART_EXPORT Dart_Handle Dart_SetDeferredLoadHandler(Dart_DeferredLoadHandler handler)
DART_EXPORT const char * Dart_DebugNameToCString(void)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_CreateAppAOTSnapshotAsAssemblies(Dart_CreateLoadingUnitCallback next_callback, void *next_callback_data, bool stripped, Dart_StreamingWriteCallback write_callback, Dart_StreamingCloseCallback close_callback)
int64_t Dart_Port
Definition dart_api.h:1526
DART_EXPORT Dart_Handle Dart_GetStaticMethodClosure(Dart_Handle library, Dart_Handle cls_type, Dart_Handle function_name)
DART_EXPORT Dart_Handle Dart_NewExternalUTF16String(const uint16_t *utf16_array, intptr_t length, void *peer, intptr_t external_allocation_size, Dart_HandleFinalizer callback)
DART_EXPORT Dart_Handle Dart_ErrorGetStackTrace(Dart_Handle handle)
void(* Dart_MessageNotifyCallback)(Dart_Isolate destination_isolate)
Definition dart_api.h:1543
DART_EXPORT Dart_Handle Dart_MapKeys(Dart_Handle map)
DART_EXPORT void Dart_ShutdownIsolate(void)
DART_EXPORT Dart_Handle Dart_NewListOfTypeFilled(Dart_Handle element_type, Dart_Handle fill_object, intptr_t length)
void(* Dart_FileReadCallback)(uint8_t **data, intptr_t *file_length, void *stream)
Definition dart_api.h:792
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_CreateAppAOTSnapshotAsElfs(Dart_CreateLoadingUnitCallback next_callback, void *next_callback_data, bool stripped, Dart_StreamingWriteCallback write_callback, Dart_StreamingCloseCallback close_callback)
DART_EXPORT void Dart_KillIsolate(Dart_Isolate isolate)
DART_EXPORT Dart_Handle Dart_StringStorageSize(Dart_Handle str, intptr_t *size)
DART_EXPORT bool Dart_ShouldPauseOnExit(void)
DART_EXPORT bool Dart_IsApiError(Dart_Handle handle)
struct _Dart_Handle * Dart_Handle
Definition dart_api.h:258
DART_EXPORT bool Dart_IsPausedOnExit(void)
DART_EXPORT Dart_Handle Dart_TypeToNonNullableType(Dart_Handle type)
DART_EXPORT Dart_Handle Dart_TypedDataReleaseData(Dart_Handle object)
const char *(* Dart_RegisterKernelBlobCallback)(const uint8_t *kernel_buffer, intptr_t kernel_buffer_size)
Definition dart_api.h:882
DART_EXPORT Dart_Handle Dart_ClassName(Dart_Handle cls_type)
bool(* Dart_EntropySource)(uint8_t *buffer, intptr_t length)
Definition dart_api.h:822
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_CreateVMAOTSnapshotAsAssembly(Dart_StreamingWriteCallback callback, void *callback_data)
DART_EXPORT void Dart_ThreadEnableProfiling(void)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_CreateAppAOTSnapshotAsAssembly(Dart_StreamingWriteCallback callback, void *callback_data, bool stripped, void *debug_callback_data)
#define DART_WARN_UNUSED_RESULT
Definition dart_api.h:66
DART_EXPORT bool Dart_IsFunction(Dart_Handle handle)
DART_EXPORT bool Dart_IsTypeVariable(Dart_Handle handle)
DART_EXPORT void Dart_PropagateError(Dart_Handle handle)
DART_EXPORT bool Dart_IsByteBuffer(Dart_Handle object)
DART_EXPORT Dart_Handle Dart_True(void)
DART_EXPORT Dart_Handle Dart_NewStringFromUTF32(const int32_t *utf32_array, intptr_t length)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_Invoke(Dart_Handle target, Dart_Handle name, int number_of_arguments, Dart_Handle *arguments)
DART_EXPORT bool Dart_IsPausedOnStart(void)
DART_EXPORT Dart_PersistentHandle Dart_NewPersistentHandle(Dart_Handle object)
DART_EXPORT void Dart_SetHeapSamplingPeriod(intptr_t bytes)
DART_EXPORT bool Dart_IsVMFlagSet(const char *flag_name)
DART_EXPORT Dart_Isolate Dart_CreateIsolateInGroup(Dart_Isolate group_member, const char *name, Dart_IsolateShutdownCallback shutdown_callback, Dart_IsolateCleanupCallback cleanup_callback, void *child_isolate_data, char **error)
DART_EXPORT Dart_Handle Dart_GetDataFromByteBuffer(Dart_Handle byte_buffer)
struct _Dart_Isolate * Dart_Isolate
Definition dart_api.h:88
DART_EXPORT Dart_Handle Dart_FunctionName(Dart_Handle function)
Dart_NativeFunction(* Dart_NativeEntryResolver)(Dart_Handle name, int num_of_arguments, bool *auto_setup_scope)
Definition dart_api.h:3281
DART_EXPORT Dart_Handle Dart_DebugName(void)
DART_EXPORT Dart_Handle Dart_ReThrowException(Dart_Handle exception, Dart_Handle stacktrace)
DART_EXPORT void Dart_SetDoubleReturnValue(Dart_NativeArguments args, double retval)
DART_EXPORT bool Dart_IsPrecompiledRuntime(void)
void(* Dart_StreamingCloseCallback)(void *callback_data)
Definition dart_api.h:3971
void(* Dart_HandleFinalizer)(void *isolate_callback_data, void *peer)
Definition dart_api.h:265
void(* Dart_ThreadStartCallback)(void)
Definition dart_api.h:754
DART_EXPORT Dart_Handle Dart_GetNativeArgument(Dart_NativeArguments args, int index)
DART_EXPORT bool Dart_IsFatalError(Dart_Handle handle)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_InvokeClosure(Dart_Handle closure, int number_of_arguments, Dart_Handle *arguments)
DART_EXPORT Dart_Handle Dart_EmptyString(void)
DART_EXPORT Dart_Handle Dart_ListGetAsBytes(Dart_Handle list, intptr_t offset, uint8_t *native_array, intptr_t length)
struct _Dart_IsolateGroup * Dart_IsolateGroup
Definition dart_api.h:89
DART_EXPORT bool Dart_DetectNullSafety(const char *script_uri, const char *package_config, const char *original_working_directory, const uint8_t *snapshot_data, const uint8_t *snapshot_instructions, const uint8_t *kernel_buffer, intptr_t kernel_buffer_size)
DART_EXPORT Dart_Handle Dart_NewListOf(Dart_CoreType_Id element_type_id, intptr_t length)
const uint8_t *(* Dart_NativeEntrySymbol)(Dart_NativeFunction nf)
Definition dart_api.h:3302
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_LoadLibraryFromKernel(const uint8_t *kernel_buffer, intptr_t kernel_buffer_size)
DART_EXPORT Dart_Handle Dart_AllocateWithNativeFields(Dart_Handle type, intptr_t num_native_fields, const intptr_t *native_fields)
DART_EXPORT bool Dart_HasStickyError(void)
DART_EXPORT DART_WARN_UNUSED_RESULT bool Dart_RunLoopAsync(bool errors_are_fatal, Dart_Port on_error_port, Dart_Port on_exit_port, char **error)
DART_EXPORT Dart_Handle Dart_NewIntegerFromUint64(uint64_t value)
DART_EXPORT Dart_Handle Dart_LookupLibrary(Dart_Handle url)
DART_EXPORT Dart_Handle Dart_GetNativeInstanceField(Dart_Handle obj, int index, intptr_t *value)
void *(* Dart_FfiNativeResolver)(const char *name, uintptr_t args_n)
Definition dart_api.h:3309
DART_EXPORT Dart_Handle Dart_TypedDataAcquireData(Dart_Handle object, Dart_TypedData_Type *type, void **data, intptr_t *len)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_SortClasses(void)
DART_EXPORT Dart_Handle Dart_IsLegacyType(Dart_Handle type, bool *result)
DART_EXPORT Dart_Handle Dart_ThrowException(Dart_Handle exception)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_FinalizeLoading(bool complete_futures)
DART_EXPORT Dart_Handle Dart_IntegerToHexCString(Dart_Handle integer, const char **value)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_InvokeConstructor(Dart_Handle object, Dart_Handle name, int number_of_arguments, Dart_Handle *arguments)
DART_EXPORT Dart_Handle Dart_GetNativeInstanceFieldCount(Dart_Handle obj, int *count)
DART_EXPORT Dart_Handle Dart_NewExternalTypedDataWithFinalizer(Dart_TypedData_Type type, void *data, intptr_t length, void *peer, intptr_t external_allocation_size, Dart_HandleFinalizer callback)
DART_EXPORT DART_WARN_UNUSED_RESULT char * Dart_Initialize(Dart_InitializeParams *params)
struct _Dart_NativeArguments * Dart_NativeArguments
Definition dart_api.h:3066
bool(* Dart_InitializeIsolateCallback)(void **child_isolate_data, char **error)
Definition dart_api.h:693
DART_EXPORT void Dart_NotifyIdle(int64_t deadline)
DART_EXPORT Dart_Handle Dart_ClosureFunction(Dart_Handle closure)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_New(Dart_Handle type, Dart_Handle constructor_name, int number_of_arguments, Dart_Handle *arguments)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_SetField(Dart_Handle container, Dart_Handle name, Dart_Handle value)
Dart_TypedData_Type
Definition dart_api.h:2659
@ Dart_TypedData_kFloat32x4
Definition dart_api.h:2673
@ Dart_TypedData_kInt32x4
Definition dart_api.h:2672
@ Dart_TypedData_kUint8
Definition dart_api.h:2662
@ Dart_TypedData_kUint32
Definition dart_api.h:2667
@ Dart_TypedData_kInt32
Definition dart_api.h:2666
@ Dart_TypedData_kUint16
Definition dart_api.h:2665
@ Dart_TypedData_kFloat64x2
Definition dart_api.h:2674
@ Dart_TypedData_kUint64
Definition dart_api.h:2669
@ Dart_TypedData_kFloat32
Definition dart_api.h:2670
@ Dart_TypedData_kInt16
Definition dart_api.h:2664
@ Dart_TypedData_kFloat64
Definition dart_api.h:2671
@ Dart_TypedData_kUint8Clamped
Definition dart_api.h:2663
@ Dart_TypedData_kByteData
Definition dart_api.h:2660
@ Dart_TypedData_kInt8
Definition dart_api.h:2661
@ Dart_TypedData_kInt64
Definition dart_api.h:2668
@ Dart_TypedData_kInvalid
Definition dart_api.h:2675
DART_EXPORT Dart_Handle Dart_SetNativeInstanceField(Dart_Handle obj, int index, intptr_t value)
DART_EXPORT Dart_Handle Dart_GetNativeIntegerArgument(Dart_NativeArguments args, int index, int64_t *value)
DART_EXPORT int Dart_GetNativeArgumentCount(Dart_NativeArguments args)
DART_EXPORT Dart_Isolate Dart_CurrentIsolate(void)
DART_EXPORT Dart_Handle Dart_NewTypedData(Dart_TypedData_Type type, intptr_t length)
DART_EXPORT bool Dart_IsKernel(const uint8_t *buffer, intptr_t buffer_size)
Dart_Handle Dart_PersistentHandle
Definition dart_api.h:259
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_GetObfuscationMap(uint8_t **buffer, intptr_t *buffer_length)
DART_EXPORT Dart_Handle Dart_False(void)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_CreateSnapshot(uint8_t **vm_snapshot_data_buffer, intptr_t *vm_snapshot_data_size, uint8_t **isolate_snapshot_data_buffer, intptr_t *isolate_snapshot_data_size, bool is_core)
void(* Dart_IsolateGroupCleanupCallback)(void *isolate_group_data)
Definition dart_api.h:745
DART_EXPORT Dart_Handle Dart_TypeToNullableType(Dart_Handle type)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_LoadLibrary(Dart_Handle kernel_buffer)
DART_EXPORT Dart_Handle Dart_SetEnvironmentCallback(Dart_EnvironmentCallback callback)
DART_EXPORT bool Dart_IsUnhandledExceptionError(Dart_Handle handle)
DART_EXPORT Dart_Handle Dart_NewApiError(const char *error)
DART_EXPORT void Dart_DeleteWeakPersistentHandle(Dart_WeakPersistentHandle object)
DART_EXPORT Dart_Handle Dart_TypeDynamic(void)
DART_EXPORT Dart_Handle Dart_Null(void)
struct _Dart_FinalizableHandle * Dart_FinalizableHandle
Definition dart_api.h:261
void(* Dart_OnNewCodeCallback)(struct Dart_CodeObserver *observer, const char *name, uintptr_t base, uintptr_t size)
Definition dart_api.h:855
DART_EXPORT Dart_KernelCompilationResult Dart_CompileToKernel(const char *script_uri, const uint8_t *platform_kernel, const intptr_t platform_kernel_size, bool incremental_compile, bool snapshot_compile, bool embed_sources, const char *package_config, Dart_KernelCompilationVerbosityLevel verbosity)
Dart_LibraryTag
Definition dart_api.h:3395
@ Dart_kImportTag
Definition dart_api.h:3397
@ Dart_kCanonicalizeUrl
Definition dart_api.h:3396
@ Dart_kKernelTag
Definition dart_api.h:3398
DART_EXPORT Dart_Handle Dart_Precompile(void)
void(* Dart_CreateLoadingUnitCallback)(void *callback_data, intptr_t loading_unit_id, void **write_callback_data, void **write_debug_callback_data)
Definition dart_api.h:3963
void *(* Dart_FileOpenCallback)(const char *name, bool write)
Definition dart_api.h:776
DART_EXPORT Dart_Handle Dart_GetNativeSymbol(Dart_Handle library, Dart_NativeEntrySymbol *resolver)
void(* Dart_IsolateShutdownCallback)(void *isolate_group_data, void *isolate_data)
Definition dart_api.h:711
DART_EXPORT DART_WARN_UNUSED_RESULT char * Dart_Cleanup(void)
DART_EXPORT Dart_WeakPersistentHandle Dart_NewWeakPersistentHandle(Dart_Handle object, void *peer, intptr_t external_allocation_size, Dart_HandleFinalizer callback)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_DeferredLoadComplete(intptr_t loading_unit_id, const uint8_t *snapshot_data, const uint8_t *snapshot_instructions)
DART_EXPORT Dart_Handle Dart_GetNativeReceiver(Dart_NativeArguments args, intptr_t *value)
DART_EXPORT const char * Dart_IsolateServiceId(Dart_Isolate isolate)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_CreateAppJITSnapshotAsBlobs(uint8_t **isolate_snapshot_data_buffer, intptr_t *isolate_snapshot_data_size, uint8_t **isolate_snapshot_instructions_buffer, intptr_t *isolate_snapshot_instructions_size)
DART_EXPORT Dart_Handle Dart_GetPeer(Dart_Handle object, void **peer)
union _Dart_NativeArgument_Value Dart_NativeArgument_Value
DART_EXPORT Dart_Handle Dart_StringToLatin1(Dart_Handle str, uint8_t *latin1_array, intptr_t *length)
DART_EXPORT bool Dart_KernelIsolateIsRunning(void)
DART_EXPORT Dart_Handle Dart_ErrorGetException(Dart_Handle handle)
DART_EXPORT void Dart_SetDartLibrarySourcesKernel(const uint8_t *platform_kernel, const intptr_t platform_kernel_size)
DART_EXPORT void Dart_SetReturnValue(Dart_NativeArguments args, Dart_Handle retval)
DART_EXPORT void Dart_SetWeakHandleReturnValue(Dart_NativeArguments args, Dart_WeakPersistentHandle rval)
void(* Dart_ThreadExitCallback)(void)
Definition dart_api.h:763
DART_EXPORT Dart_Handle Dart_StringToUTF8(Dart_Handle str, uint8_t **utf8_array, intptr_t *length)
DART_EXPORT Dart_Handle Dart_MapContainsKey(Dart_Handle map, Dart_Handle key)
DART_EXPORT Dart_Handle Dart_LibraryResolvedUrl(Dart_Handle library)
DART_EXPORT Dart_Handle Dart_GetClass(Dart_Handle library, Dart_Handle class_name)
DART_EXPORT Dart_Handle Dart_ListLength(Dart_Handle list, intptr_t *length)
DART_EXPORT Dart_Handle Dart_NewByteBuffer(Dart_Handle typed_data)
DART_EXPORT bool Dart_IsNull(Dart_Handle object)
DART_EXPORT void Dart_SetShouldPauseOnExit(bool should_pause)
DART_EXPORT void Dart_NotifyDestroyed(void)
DART_EXPORT Dart_Port Dart_GetMainPortId(void)
DART_EXPORT void Dart_SetDwarfStackTraceFootnoteCallback(Dart_DwarfStackTraceFootnoteCallback callback)
DART_EXPORT Dart_Handle Dart_NewExternalLatin1String(const uint8_t *latin1_array, intptr_t length, void *peer, intptr_t external_allocation_size, Dart_HandleFinalizer callback)
DART_EXPORT Dart_Handle Dart_IntegerFitsIntoInt64(Dart_Handle integer, bool *fits)
DART_EXPORT uint8_t * Dart_ScopeAllocate(intptr_t size)
DART_EXPORT Dart_Isolate Dart_CreateIsolateGroupFromKernel(const char *script_uri, const char *name, const uint8_t *kernel_buffer, intptr_t kernel_buffer_size, Dart_IsolateFlags *flags, void *isolate_group_data, void *isolate_data, char **error)
DART_EXPORT void * Dart_IsolateData(Dart_Isolate isolate)
DART_EXPORT void Dart_SetStickyError(Dart_Handle error)
DART_EXPORT void Dart_AddSymbols(const char *dso_name, void *buffer, intptr_t buffer_size)
DART_EXPORT bool Dart_ErrorHasException(Dart_Handle handle)
DART_EXPORT Dart_Handle Dart_StringToCString(Dart_Handle str, const char **cstr)
void *(* Dart_HeapSamplingCreateCallback)(Dart_Isolate isolate, Dart_IsolateGroup isolate_group, const char *cls_name, intptr_t allocation_size)
Definition dart_api.h:1284
DART_EXPORT Dart_Handle Dart_ObjectIsType(Dart_Handle object, Dart_Handle type, bool *instanceof)
DART_EXPORT Dart_Handle Dart_NewStringFromCString(const char *str)
DART_EXPORT Dart_Handle Dart_SendPortGetId(Dart_Handle port, Dart_Port *port_id)
void(* Dart_NativeFunction)(Dart_NativeArguments arguments)
Definition dart_api.h:3254
Dart_Handle(* Dart_GetVMServiceAssetsArchive)(void)
Definition dart_api.h:834
DART_EXPORT bool Dart_IdentityEquals(Dart_Handle obj1, Dart_Handle obj2)
DART_EXPORT void * Dart_IsolateGroupData(Dart_Isolate isolate)
DART_EXPORT Dart_Handle Dart_GetStickyError(void)
@ kNativeArgNumberPos
Definition dart_api.h:3109
@ kNativeArgNumberSize
Definition dart_api.h:3110
@ kNativeArgTypePos
Definition dart_api.h:3111
@ kNativeArgTypeSize
Definition dart_api.h:3112
DART_EXPORT Dart_Handle Dart_NewUnmodifiableExternalTypedDataWithFinalizer(Dart_TypedData_Type type, const void *data, intptr_t length, void *peer, intptr_t external_allocation_size, Dart_HandleFinalizer callback)
DART_EXPORT Dart_IsolateGroup Dart_CurrentIsolateGroup(void)
DART_EXPORT Dart_Handle Dart_NewInteger(int64_t value)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_GetField(Dart_Handle container, Dart_Handle name)
DART_EXPORT void Dart_RegisterHeapSamplingCallback(Dart_HeapSamplingCreateCallback create_callback, Dart_HeapSamplingDeleteCallback delete_callback)
DART_EXPORT bool Dart_IsType(Dart_Handle handle)
DART_EXPORT Dart_Handle Dart_DoubleValue(Dart_Handle double_obj, double *value)
DART_EXPORT Dart_Handle Dart_GetNativeArguments(Dart_NativeArguments args, int num_arguments, const Dart_NativeArgument_Descriptor *arg_descriptors, Dart_NativeArgument_Value *arg_values)
Dart_Handle(* Dart_LibraryTagHandler)(Dart_LibraryTag tag, Dart_Handle library_or_package_map_url, Dart_Handle url)
Definition dart_api.h:3434
DART_EXPORT Dart_Handle Dart_NewBoolean(bool value)
DART_EXPORT void Dart_EnterIsolate(Dart_Isolate isolate)
DART_EXPORT void Dart_NotifyLowMemory(void)
Dart_NativeArgument_Type
Definition dart_api.h:3073
@ Dart_NativeArgument_kString
Definition dart_api.h:3080
@ Dart_NativeArgument_kInt64
Definition dart_api.h:3077
@ Dart_NativeArgument_kNativeFields
Definition dart_api.h:3082
@ Dart_NativeArgument_kInstance
Definition dart_api.h:3081
@ Dart_NativeArgument_kInt32
Definition dart_api.h:3075
@ Dart_NativeArgument_kUint64
Definition dart_api.h:3078
@ Dart_NativeArgument_kUint32
Definition dart_api.h:3076
@ Dart_NativeArgument_kDouble
Definition dart_api.h:3079
@ Dart_NativeArgument_kBool
Definition dart_api.h:3074
DART_EXPORT Dart_Handle Dart_DefaultCanonicalizeUrl(Dart_Handle base_url, Dart_Handle url)
DART_EXPORT void Dart_SetBooleanReturnValue(Dart_NativeArguments args, bool retval)
DART_EXPORT Dart_Handle Dart_InstanceGetType(Dart_Handle instance)
DART_EXPORT bool Dart_IsVariable(Dart_Handle handle)
DART_EXPORT void Dart_SetShouldPauseOnStart(bool should_pause)
DART_EXPORT Dart_Handle Dart_GetNativeFieldsOfArgument(Dart_NativeArguments args, int arg_index, int num_fields, intptr_t *field_values)
DART_EXPORT Dart_MessageNotifyCallback Dart_GetMessageNotifyCallback(void)
int64_t Dart_IsolateGroupId
Definition dart_api.h:1209
DART_EXPORT Dart_Handle Dart_LibraryUrl(Dart_Handle library)
DART_EXPORT void Dart_SetPersistentHandle(Dart_PersistentHandle obj1, Dart_Handle obj2)
char *(* Dart_DwarfStackTraceFootnoteCallback)(void *addresses[], intptr_t count)
Definition dart_api.h:4178
DART_EXPORT Dart_Handle Dart_LibraryHandleError(Dart_Handle library, Dart_Handle error)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_LoadScriptFromKernel(const uint8_t *kernel_buffer, intptr_t kernel_size)
DART_EXPORT Dart_PerformanceMode Dart_SetPerformanceMode(Dart_PerformanceMode mode)
DART_EXPORT Dart_Handle Dart_ObjectEquals(Dart_Handle obj1, Dart_Handle obj2, bool *equal)
DART_EXPORT DART_WARN_UNUSED_RESULT char * Dart_SetVMFlags(int argc, const char **argv)
DART_EXPORT void * Dart_GetNativeIsolateGroupData(Dart_NativeArguments args)
DART_EXPORT bool Dart_IsError(Dart_Handle handle)
DART_EXPORT Dart_Handle Dart_NewList(intptr_t length)
DART_EXPORT Dart_Handle Dart_NewStringFromUTF16(const uint16_t *utf16_array, intptr_t length)
DART_EXPORT Dart_Handle Dart_StringGetProperties(Dart_Handle str, intptr_t *char_size, intptr_t *str_len, void **peer)
struct _Dart_WeakPersistentHandle * Dart_WeakPersistentHandle
Definition dart_api.h:260
Dart_KernelCompilationVerbosityLevel
Definition dart_api.h:3797
@ Dart_KernelCompilationVerbosityLevel_Error
Definition dart_api.h:3798
@ Dart_KernelCompilationVerbosityLevel_Warning
Definition dart_api.h:3799
@ Dart_KernelCompilationVerbosityLevel_All
Definition dart_api.h:3801
@ Dart_KernelCompilationVerbosityLevel_Info
Definition dart_api.h:3800
DART_EXPORT bool Dart_Post(Dart_Port port_id, Dart_Handle object)
DART_EXPORT Dart_Handle Dart_GetNullableType(Dart_Handle library, Dart_Handle class_name, intptr_t number_of_type_arguments, Dart_Handle *type_arguments)
DART_EXPORT void Dart_DeleteFinalizableHandle(Dart_FinalizableHandle object, Dart_Handle strong_ref_to_object)
DART_EXPORT Dart_Handle Dart_StringUTF8Length(Dart_Handle str, intptr_t *length)
DART_EXPORT void Dart_EnableHeapSampling(void)
DART_EXPORT bool Dart_ShouldPauseOnStart(void)
DART_EXPORT bool Dart_IsDouble(Dart_Handle object)
DART_EXPORT void Dart_ExitIsolate(void)
DART_EXPORT bool Dart_IsServiceIsolate(Dart_Isolate isolate)
Dart_Handle(* Dart_DeferredLoadHandler)(intptr_t loading_unit_id)
Definition dart_api.h:3469
DART_EXPORT void * Dart_CurrentIsolateGroupData(void)
DART_EXPORT void Dart_ReportSurvivingAllocations(Dart_HeapSamplingReportCallback callback, void *context, bool force_gc)
DART_EXPORT Dart_Handle Dart_HandleFromWeakPersistent(Dart_WeakPersistentHandle object)
DART_EXPORT Dart_Handle Dart_ListGetAt(Dart_Handle list, intptr_t index)
DART_EXPORT void Dart_DeletePersistentHandle(Dart_PersistentHandle object)
DART_EXPORT Dart_Handle Dart_CopyUTF8EncodingOfString(Dart_Handle str, uint8_t *utf8_array, intptr_t length)
DART_EXPORT void Dart_SetMessageNotifyCallback(Dart_MessageNotifyCallback message_notify_callback)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_DeferredLoadCompleteError(intptr_t loading_unit_id, const char *error_message, bool transient)
DART_EXPORT Dart_Handle Dart_MapGetAt(Dart_Handle map, Dart_Handle key)
DART_EXPORT Dart_Handle Dart_IsNonNullableType(Dart_Handle type, bool *result)
DART_EXPORT Dart_IsolateGroupId Dart_CurrentIsolateGroupId(void)
DART_EXPORT bool Dart_IsString(Dart_Handle object)
DART_EXPORT const char * Dart_GetError(Dart_Handle handle)
DART_EXPORT bool Dart_IsKernelIsolate(Dart_Isolate isolate)
DART_EXPORT Dart_Handle Dart_NewListOfType(Dart_Handle element_type, intptr_t length)
DART_EXPORT Dart_Handle Dart_NewIntegerFromHexCString(const char *value)
DART_EXPORT Dart_Handle Dart_NewUnhandledExceptionError(Dart_Handle exception)
DART_EXPORT Dart_Handle Dart_ToString(Dart_Handle object)
DART_EXPORT Dart_Handle Dart_SetPeer(Dart_Handle object, void *peer)
DART_EXPORT Dart_Handle Dart_BooleanValue(Dart_Handle boolean_obj, bool *value)
DART_EXPORT Dart_Handle Dart_ClassLibrary(Dart_Handle cls_type)
void(* Dart_HeapSamplingDeleteCallback)(void *data)
Definition dart_api.h:1289
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_RunLoop(void)
DART_EXPORT bool Dart_IsClosure(Dart_Handle object)
DART_EXPORT Dart_Handle Dart_IntegerFitsIntoUint64(Dart_Handle integer, bool *fits)
DART_EXPORT Dart_Handle Dart_GetLoadedLibraries(void)
DART_EXPORT bool Dart_IsLibrary(Dart_Handle object)
DART_EXPORT Dart_Handle Dart_SetLibraryTagHandler(Dart_LibraryTagHandler handler)
DART_EXPORT bool Dart_IsTearOff(Dart_Handle object)
DART_EXPORT Dart_Handle Dart_RootLibrary(void)
DART_EXPORT bool Dart_IsFuture(Dart_Handle object)
DART_EXPORT bool Dart_HasLivePorts(void)
DART_EXPORT bool Dart_IsList(Dart_Handle object)
DART_EXPORT bool Dart_IsExternalString(Dart_Handle object)
DART_EXPORT Dart_Handle Dart_GetNativeDoubleArgument(Dart_NativeArguments args, int index, double *value)
struct _Dart_NativeArgument_Descriptor Dart_NativeArgument_Descriptor
DART_EXPORT Dart_Handle Dart_ListSetAt(Dart_Handle list, intptr_t index, Dart_Handle value)
DART_EXPORT Dart_Handle Dart_IntegerToUint64(Dart_Handle integer, uint64_t *value)
DART_EXPORT bool Dart_IsCompilationError(Dart_Handle handle)
DART_EXPORT bool Dart_IsMap(Dart_Handle object)
void(* Dart_HeapSamplingReportCallback)(void *context, void *data)
Definition dart_api.h:1281
DART_EXPORT Dart_Handle Dart_NewCompilationError(const char *error)
DART_EXPORT bool Dart_IsTypedData(Dart_Handle object)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_WaitForEvent(int64_t timeout_millis)
DART_EXPORT Dart_Handle Dart_GetNativeStringArgument(Dart_NativeArguments args, int arg_index, void **peer)
DART_EXPORT Dart_Handle Dart_LoadingUnitLibraryUris(intptr_t loading_unit_id)
DART_EXPORT DART_WARN_UNUSED_RESULT Dart_Handle Dart_HandleMessage(void)
DART_EXPORT Dart_Handle Dart_GetNativeBooleanArgument(Dart_NativeArguments args, int index, bool *value)
DART_EXPORT Dart_Handle Dart_SetRootLibrary(Dart_Handle library)
DART_EXPORT Dart_TypedData_Type Dart_GetTypeOfTypedData(Dart_Handle object)
const EmbeddedViewParams * params
VkInstance instance
Definition main.cc:47
#define DART_EXPORT
FlutterSemanticsFlag flags
G_BEGIN_DECLS G_MODULE_EXPORT FlValue * args
FlKeyEvent uint64_t FlKeyResponderAsyncCallback callback
static const uint8_t buffer[]
const uint8_t uint32_t uint32_t GError ** error
GAsyncResult * result
uint32_t * target
Dart_NativeFunction function
Definition fuchsia.cc:51
const char * name
Definition fuchsia.cc:50
size_t length
Definition main.py:1
void write(SkWStream *wStream, const T &text)
Definition skqp.cpp:188
Point offset
Dart_OnNewCodeCallback on_new_code
Definition dart_api.h:863
Dart_ThreadExitCallback thread_exit
Definition dart_api.h:953
Dart_IsolateGroupCreateCallback create_group
Definition dart_api.h:925
Dart_InitializeIsolateCallback initialize_isolate
Definition dart_api.h:932
Dart_IsolateGroupCleanupCallback cleanup_group
Definition dart_api.h:950
Dart_FileReadCallback file_read
Definition dart_api.h:955
const uint8_t * vm_snapshot_data
Definition dart_api.h:911
Dart_GetVMServiceAssetsArchive get_service_assets
Definition dart_api.h:964
Dart_FileOpenCallback file_open
Definition dart_api.h:954
Dart_IsolateShutdownCallback shutdown_isolate
Definition dart_api.h:938
Dart_ThreadStartCallback thread_start
Definition dart_api.h:952
Dart_CodeObserver * code_observer
Definition dart_api.h:972
Dart_UnregisterKernelBlobCallback unregister_kernel_blob
Definition dart_api.h:982
Dart_FileWriteCallback file_write
Definition dart_api.h:956
Dart_EntropySource entropy_source
Definition dart_api.h:958
Dart_RegisterKernelBlobCallback register_kernel_blob
Definition dart_api.h:977
Dart_IsolateCleanupCallback cleanup_isolate
Definition dart_api.h:944
const uint8_t * vm_snapshot_instructions
Definition dart_api.h:919
Dart_FileCloseCallback file_close
Definition dart_api.h:957
bool is_service_isolate
Definition dart_api.h:594
bool load_vmservice_library
Definition dart_api.h:591
bool snapshot_is_dontneed_safe
Definition dart_api.h:596
Dart_KernelCompilationStatus status
Definition dart_api.h:3791
const char * uri
Definition dart_api.h:3849
const char * source
Definition dart_api.h:3850
struct _Dart_NativeArgument_Value::@82 as_string
struct _Dart_NativeArgument_Value::@83 as_native_fields