Ivan Inozemtsev
6e33c95463
Adds shared libraries for embedding Dart VM and new API (runtime/engine/include/dart_engine.h). TEST=tests/standalone/embedder_samples_test.dart Cq-Include-Trybots: luci.dart.try:vm-aot-android-release-arm64c-try,vm-aot-android-release-arm_x64-try,vm-aot-asan-linux-release-x64-try,vm-aot-dwarf-linux-product-x64-try,vm-aot-dyn-linux-debug-x64-try,vm-aot-linux-debug-simarm_x64-try,vm-aot-linux-debug-simriscv32-try,vm-aot-linux-debug-simriscv64-try,vm-aot-linux-debug-x64-try,vm-aot-linux-debug-x64c-try,vm-aot-linux-product-x64-try,vm-aot-linux-release-arm64-try,vm-aot-linux-release-simarm_x64-try,vm-aot-linux-release-x64-try,vm-aot-mac-product-arm64-try,vm-aot-mac-release-arm64-try,vm-aot-mac-release-x64-try,vm-aot-msan-linux-release-x64-try,vm-aot-obfuscate-linux-release-x64-try,vm-aot-optimization-level-linux-release-x64-try,vm-aot-tsan-linux-release-x64-try,vm-aot-ubsan-linux-release-x64-try,vm-aot-win-debug-x64-try,vm-aot-win-debug-x64c-try,vm-aot-win-product-x64-try,vm-aot-win-release-x64-try,vm-appjit-linux-debug-x64-try,vm-appjit-linux-product-x64-try,vm-appjit-linux-release-x64-try,vm-asan-linux-release-arm64-try,vm-asan-linux-release-x64-try,vm-checked-mac-release-arm64-try,vm-eager-optimization-linux-release-ia32-try,vm-eager-optimization-linux-release-x64-try,vm-ffi-android-debug-arm-try,vm-ffi-android-debug-arm64c-try,vm-ffi-android-product-arm-try,vm-ffi-android-product-arm64c-try,vm-ffi-android-release-arm-try,vm-ffi-android-release-arm64c-try,vm-ffi-qemu-linux-release-arm-try,vm-ffi-qemu-linux-release-riscv64-try,vm-fuchsia-release-arm64-try,vm-fuchsia-release-x64-try,vm-gcc-linux-try,vm-linux-debug-ia32-try,vm-linux-debug-simriscv32-try,vm-linux-debug-simriscv64-try,vm-linux-debug-x64-try,vm-linux-debug-x64c-try,vm-linux-release-arm64-try,vm-linux-release-ia32-try,vm-linux-release-simarm-try,vm-linux-release-x64-try,vm-mac-debug-arm64-try,vm-mac-debug-x64-try,vm-mac-release-arm64-try,vm-mac-release-x64-try,vm-msan-linux-release-arm64-try,vm-msan-linux-release-x64-try,vm-msvc-windows-try,vm-reload-linux-debug-x64-try,vm-reload-linux-release-x64-try,vm-reload-rollback-linux-debug-x64-try,vm-reload-rollback-linux-release-x64-try,vm-tsan-linux-release-arm64-try,vm-tsan-linux-release-x64-try,vm-ubsan-linux-release-arm64-try,vm-ubsan-linux-release-x64-try,vm-win-debug-x64-try,vm-win-debug-x64c-try,vm-win-release-ia32-try,vm-win-release-x64-try Change-Id: Ia4e4d1b871ddef515cfb2f4639bdaa9fe3676936 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/402860 Reviewed-by: Slava Egorov <vegorov@google.com> Reviewed-by: Martin Kustermann <kustermann@google.com> Commit-Queue: Martin Kustermann <kustermann@google.com>
49 lines
2.2 KiB
Markdown
49 lines
2.2 KiB
Markdown
# Dart Engine
|
|
|
|
The `include/dart_engine.h` provides additional functions to embed the Dart VM
|
|
and to call Dart functions from kernel and AOT snapshots. It is not intended to
|
|
be a full-featured API, and should be used together with `dart_api.h`.
|
|
|
|
It is intended for reusing of existing Dart code in non-Dart programs, and
|
|
allows to use Dart snapshots as shared libraries: the caller can start one or
|
|
several isolates from Dart snapshots and call Dart functions from it.
|
|
|
|
Comparing to `dart_api.h` it brings the following:
|
|
|
|
- Full initialization of Dart VM, including initializing core libraries.
|
|
- Easier handling of isolate messages
|
|
- Lock-guarded functions to enter/exit isolates.
|
|
|
|
See examples in `samples/embedder` for usages of the API.
|
|
|
|
## Handling isolate messages
|
|
|
|
In `dart_api.h` there are two possible ways to handle asynchronous
|
|
isolate messages:
|
|
|
|
- `Dart_MessageNotifyCallback`: Users can pass a callback to get
|
|
notifications about messages to handle, but handling messages still
|
|
requires entering an isolate, entering a scope, calling
|
|
`Dart_HandleMessage`, and then leaving a scope and an isolate.
|
|
- `Dart_RunLoop`: Users can invoke it on a separate thread, but then they won't
|
|
be able to enter isolates from other threads.
|
|
|
|
As an alternative, `dart_engine.h` provides a simpler function
|
|
`DartEngine_HandleMessage`, which encapsulates isolate and scope management, and
|
|
it allows to specify per isolate / default message schedulers, which only need
|
|
to schedule an execution `DartEngine_HandleMessage` with the right isolate.
|
|
|
|
Users can create their own `DartEngine_MessageScheduler` struct and pass it to
|
|
`DartEngine_SetMessageScheduler` / `DartEngine_SetDefaultMessageScheduler`. See
|
|
`samples/embedder/run_timer_async.cc` and `samples/embedder/run_timer.cc`
|
|
examples.
|
|
|
|
## Entering / leaving isolates
|
|
|
|
Because engine API uses its own message handling, it is important to use
|
|
`DartEngine_AcquireIsolate` / `DartEngine_ReleaseIsolate` instead of
|
|
`Dart_EnterIsolate` / `Dart_ExitIsolate`. `DartEngine_AcquireIsolate` blocks
|
|
until an isolate can be entered by trying to obtain an internal lock (which is
|
|
released by `DartEngine_ReleaseIsolate`), while `Dart_EnterIsolate` crashes if
|
|
some other thread has entered the same isolate.
|