forked from flutter/engine
-
Notifications
You must be signed in to change notification settings - Fork 0
/
isolate_configuration.h
171 lines (154 loc) · 8.1 KB
/
isolate_configuration.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
// Copyright 2013 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef FLUTTER_SHELL_RUNTIME_ISOLATE_CONFIGURATION_H_
#define FLUTTER_SHELL_RUNTIME_ISOLATE_CONFIGURATION_H_
#include <future>
#include <memory>
#include <string>
#include "flutter/assets/asset_manager.h"
#include "flutter/assets/asset_resolver.h"
#include "flutter/common/settings.h"
#include "flutter/fml/macros.h"
#include "flutter/fml/mapping.h"
#include "flutter/fml/memory/weak_ptr.h"
#include "flutter/runtime/dart_isolate.h"
namespace flutter {
//------------------------------------------------------------------------------
/// @brief An isolate configuration is a collection of snapshots and asset
/// managers that the engine will use to configure the isolate
/// before invoking its root entrypoint. The set of snapshots must
/// be sufficient for the engine to move the isolate from the
/// |DartIsolate::Phase::LibrariesSetup| phase to the
/// |DartIsolate::Phase::Ready| phase. Note that the isolate
/// configuration will not be collected till the isolate tied to the
/// configuration as well as any and all child isolates of that
/// isolate are collected. The engine may ask the configuration to
/// prepare multiple isolates. All subclasses of this class must be
/// thread safe as the configuration may be created, collected and
/// used on multiple threads. Usually these threads are engine or VM
/// managed so care must be taken to ensure that subclasses do not
/// reference any thread local state.
///
class IsolateConfiguration {
public:
//----------------------------------------------------------------------------
/// @brief Attempts to infer the isolate configuration from the
/// `Settings` object. If the VM is configured for AOT mode,
/// snapshot resolution is attempted with predefined symbols
/// present in the currently loaded process. In JIT mode, Dart
/// kernel file resolution is attempted in the assets directory.
/// If an IO worker is specified, snapshot resolution may be
/// attempted on the serial worker task runner. The worker task
/// runner thread must remain valid and running till after the
/// shell associated with the engine used to launch the isolate
/// for which this run configuration is used is collected.
///
/// @param[in] settings The settings
/// @param[in] asset_manager The optional asset manager. This is used when
/// using the legacy settings fields that specify
/// the asset by name instead of a mappings
/// callback.
/// @param[in] io_worker An optional IO worker. Specify `nullptr` if a
/// worker should not be used or one is not
/// available.
///
/// @return An isolate configuration if one can be inferred from the
/// settings. If not, returns `nullptr`.
///
[[nodiscard]] static std::unique_ptr<IsolateConfiguration> InferFromSettings(
const Settings& settings,
std::shared_ptr<AssetManager> asset_manager = nullptr,
fml::RefPtr<fml::TaskRunner> io_worker = nullptr);
//----------------------------------------------------------------------------
/// @brief Creates an AOT isolate configuration using snapshot symbols
/// present in the currently loaded process. These symbols need to
/// be given to the Dart VM on bootstrap and hence have already
/// been resolved.
///
/// @return An AOT isolate configuration.
///
static std::unique_ptr<IsolateConfiguration> CreateForAppSnapshot();
//----------------------------------------------------------------------------
/// @brief Creates a JIT isolate configuration using a list of futures to
/// snapshots defining the ready isolate state. In environments
/// where snapshot resolution is extremely expensive, embedders
/// attempt to resolve snapshots on worker thread(s) and return
/// the future of the promise of snapshot resolution to this
/// method. That way, snapshot resolution begins well before
/// isolate launch is attempted by the engine.
///
/// @param[in] kernel_pieces The list of futures to Dart kernel snapshots.
///
/// @return A JIT isolate configuration.
///
static std::unique_ptr<IsolateConfiguration> CreateForKernelList(
std::vector<std::future<std::unique_ptr<const fml::Mapping>>>
kernel_pieces);
//----------------------------------------------------------------------------
/// @brief Creates a JIT isolate configuration using the specified
/// snapshot. This is a convenience method for the
/// `CreateForKernelList` method that takes a list of futures to
/// Dart kernel snapshots.
///
/// @see CreateForKernelList()
///
/// @param[in] kernel The kernel snapshot.
///
/// @return A JIT isolate configuration.
///
static std::unique_ptr<IsolateConfiguration> CreateForKernel(
std::unique_ptr<const fml::Mapping> kernel);
//----------------------------------------------------------------------------
/// @brief Creates a JIT isolate configuration using the specified
/// snapshots. This is a convenience method for the
/// `CreateForKernelList` method that takes a list of futures to
/// Dart kernel snapshots.
///
/// @see CreateForKernelList()
///
/// @param[in] kernel_pieces The kernel pieces
///
/// @return { description_of_the_return_value }
///
static std::unique_ptr<IsolateConfiguration> CreateForKernelList(
std::vector<std::unique_ptr<const fml::Mapping>> kernel_pieces);
//----------------------------------------------------------------------------
/// @brief Create an isolate configuration. This has no threading
/// restrictions.
///
IsolateConfiguration();
//----------------------------------------------------------------------------
/// @brief Destroys an isolate configuration. This has no threading
/// restrictions and may be collection of configurations may occur
/// on any thread (and usually happens on an internal VM managed
/// thread pool thread).
///
virtual ~IsolateConfiguration();
//----------------------------------------------------------------------------
/// @brief When an isolate is created and sufficiently initialized to
/// move it into the `DartIsolate::Phase::LibrariesSetup` phase,
/// this method is invoked on the isolate to then move the isolate
/// into the `DartIsolate::Phase::Ready` phase. Then isolate's
/// main entrypoint is then invoked to move it into the
/// `DartIsolate::Phase::Running` phase. This method will be
/// called each time the root isolate is launched (which may be
/// multiple times in cold-restart scenarios) as well as one each
/// for any child isolates referenced by that isolate.
///
/// @param isolate The isolate which is already in the
/// `DartIsolate::Phase::LibrariesSetup` phase.
///
/// @return Returns true if the isolate could be configured. Unless this
/// returns true, the engine will not move the isolate to the
/// `DartIsolate::Phase::Ready` phase for subsequent run.
///
[[nodiscard]] bool PrepareIsolate(DartIsolate& isolate);
virtual bool IsNullSafetyEnabled(const DartSnapshot& snapshot) = 0;
protected:
virtual bool DoPrepareIsolate(DartIsolate& isolate) = 0;
private:
FML_DISALLOW_COPY_AND_ASSIGN(IsolateConfiguration);
};
} // namespace flutter
#endif // FLUTTER_SHELL_RUNTIME_ISOLATE_CONFIGURATION_H_