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