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
11namespace dart {
12namespace 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.
21DART_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.
27void Cleanup();
28
29// Common arguments that are passed to isolate creation callback and to
30// API methods that create isolates.
31struct 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).
54DART_WARN_UNUSED_RESULT Dart_Isolate
55CreateKernelServiceIsolate(const IsolateCreationData& data,
56 const uint8_t* buffer,
57 intptr_t buffer_size,
58 char** error);
59
60// Service isolate configuration.
61struct 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.
87DART_WARN_UNUSED_RESULT Dart_Isolate
88CreateVmServiceIsolate(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.
98DART_WARN_UNUSED_RESULT Dart_Isolate
99CreateVmServiceIsolateFromKernel(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