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