1 | // Copyright 2013 The Flutter Authors. All rights reserved. |
2 | // Use of this source code is governed by a BSD-style license that can be |
3 | // found in the LICENSE file. |
4 | |
5 | #ifndef FLUTTER_SHELL_COMMON_RUN_CONFIGURATION_H_ |
6 | #define FLUTTER_SHELL_COMMON_RUN_CONFIGURATION_H_ |
7 | |
8 | #include <memory> |
9 | #include <string> |
10 | |
11 | #include "flutter/assets/asset_manager.h" |
12 | #include "flutter/assets/asset_resolver.h" |
13 | #include "flutter/common/settings.h" |
14 | #include "flutter/fml/macros.h" |
15 | #include "flutter/fml/mapping.h" |
16 | #include "flutter/fml/unique_fd.h" |
17 | #include "flutter/runtime/isolate_configuration.h" |
18 | |
19 | namespace flutter { |
20 | |
21 | //------------------------------------------------------------------------------ |
22 | /// @brief Specifies all the configuration required by the runtime library |
23 | /// to launch the root isolate. This object may be created on any |
24 | /// thread but must be given to the |Run| call of the |Engine| on |
25 | /// the UI thread. The configuration object is used to specify how |
26 | /// the root isolate finds its snapshots, assets, root library and |
27 | /// the "main" entrypoint. |
28 | /// |
29 | class RunConfiguration { |
30 | public: |
31 | //---------------------------------------------------------------------------- |
32 | /// @brief Attempts to infer a run configuration from the settings |
33 | /// object. This tries to create a run configuration with sensible |
34 | /// defaults for the given Dart VM runtime mode. In JIT mode, this |
35 | /// will attempt to look for the VM and isolate snapshots in the |
36 | /// assets directory (must be specified in settings). In AOT mode, |
37 | /// it will attempt to look for known snapshot symbols in the |
38 | /// currently loaded process. The entrypoint defaults to |
39 | /// the "main" method in the root library. |
40 | /// |
41 | /// @param[in] settings The settings object used to look for the various |
42 | /// snapshots and settings. This is usually initialized |
43 | /// from command line arguments. |
44 | /// @param[in] io_worker An optional IO worker. Resolving and reading the |
45 | /// various snapshots may be slow. Providing an IO |
46 | /// worker will ensure that realization of these |
47 | /// snapshots happens on a worker thread instead of the |
48 | /// calling thread. Note that the work done to realize |
49 | /// the snapshots may occur after this call returns. If |
50 | /// is the embedder's responsibility to make sure the |
51 | /// serial worker is kept alive for the lifetime of the |
52 | /// shell associated with the engine that this run |
53 | /// configuration is given to. |
54 | /// |
55 | /// @return A run configuration. Depending on the completeness of the |
56 | /// settings, This object may potentially be invalid. |
57 | /// |
58 | static RunConfiguration InferFromSettings( |
59 | const Settings& settings, |
60 | const fml::RefPtr<fml::TaskRunner>& io_worker = nullptr); |
61 | |
62 | //---------------------------------------------------------------------------- |
63 | /// @brief Creates a run configuration with only an isolate |
64 | /// configuration. There is no asset manager and default |
65 | /// entrypoint and root library are used ("main" in root library). |
66 | /// |
67 | /// @param[in] configuration The configuration |
68 | /// |
69 | explicit RunConfiguration( |
70 | std::unique_ptr<IsolateConfiguration> configuration); |
71 | |
72 | //---------------------------------------------------------------------------- |
73 | /// @brief Creates a run configuration with the specified isolate |
74 | /// configuration and asset manager. The default entrypoint and |
75 | /// root library are used ("main" in root library). |
76 | /// |
77 | /// @param[in] configuration The configuration |
78 | /// @param[in] asset_manager The asset manager |
79 | /// |
80 | RunConfiguration(std::unique_ptr<IsolateConfiguration> configuration, |
81 | std::shared_ptr<AssetManager> asset_manager); |
82 | |
83 | //---------------------------------------------------------------------------- |
84 | /// @brief Run configurations cannot be copied because it may not always |
85 | /// be possible to copy the underlying isolate snapshots. If |
86 | /// multiple run configurations share the same underlying |
87 | /// snapshots, creating a configuration from isolate snapshots |
88 | /// sharing the same underlying buffers is recommended. |
89 | /// |
90 | /// @param config The run configuration to move. |
91 | /// |
92 | RunConfiguration(RunConfiguration&& config); |
93 | |
94 | //---------------------------------------------------------------------------- |
95 | /// @brief There are no threading restrictions on the destruction of the |
96 | /// run configuration. |
97 | /// |
98 | ~RunConfiguration(); |
99 | |
100 | //---------------------------------------------------------------------------- |
101 | /// @brief A valid run configuration only guarantees that the engine |
102 | /// should be able to find the assets and the isolate snapshots |
103 | /// when it attempts to launch the root isolate. The validity of |
104 | /// the snapshot cannot be determined yet. That determination can |
105 | /// only be made when the configuration is used to run the root |
106 | /// isolate in the engine. However, the engine will always reject |
107 | /// an invalid run configuration. |
108 | /// |
109 | /// @attention A valid run configuration does not mean that the root isolate |
110 | /// will always be launched. It only indicates that the various |
111 | /// snapshots are isolate snapshots and asset managers are present |
112 | /// and accounted for. The validity of the snapshots will only be |
113 | /// checked when the engine attempts to launch the root isolate. |
114 | /// |
115 | /// @return Returns whether the snapshots and asset manager registrations |
116 | /// are valid. |
117 | /// |
118 | bool IsValid() const; |
119 | |
120 | //---------------------------------------------------------------------------- |
121 | /// @brief Asset managers maintain a list of resolvers that are checked |
122 | /// in order when attempting to locate an asset. This method adds |
123 | /// a resolver to the end of the list. |
124 | /// |
125 | /// @param[in] resolver The asset resolver to add to the engine of the list |
126 | /// resolvers maintained by the asset manager. |
127 | /// |
128 | /// @return Returns whether the resolver was successfully registered. The |
129 | /// resolver must be valid for its registration to be successful. |
130 | /// |
131 | bool AddAssetResolver(std::unique_ptr<AssetResolver> resolver); |
132 | |
133 | //---------------------------------------------------------------------------- |
134 | /// @brief Updates the main application entrypoint. If this is not set, |
135 | /// the |
136 | /// "main" method is used as the entrypoint. |
137 | /// |
138 | /// @param[in] entrypoint The entrypoint to use. |
139 | void SetEntrypoint(std::string entrypoint); |
140 | |
141 | //---------------------------------------------------------------------------- |
142 | /// @brief Specifies the main Dart entrypoint and the library to find |
143 | /// that entrypoint in. By default, this is the "main" method in |
144 | /// the root library. The root library may be specified by |
145 | /// entering the empty string as the second argument. |
146 | /// |
147 | /// @see SetEntrypoint() |
148 | /// |
149 | /// @param[in] entrypoint The entrypoint |
150 | /// @param[in] library The library |
151 | /// |
152 | void SetEntrypointAndLibrary(std::string entrypoint, std::string library); |
153 | |
154 | //---------------------------------------------------------------------------- |
155 | /// @brief Updates the main application entrypoint arguments. |
156 | /// |
157 | /// @param[in] entrypoint_args The entrypoint arguments to use. |
158 | void SetEntrypointArgs(std::vector<std::string> entrypoint_args); |
159 | |
160 | //---------------------------------------------------------------------------- |
161 | /// @return The asset manager referencing all previously registered asset |
162 | /// resolvers. |
163 | /// |
164 | std::shared_ptr<AssetManager> GetAssetManager() const; |
165 | |
166 | //---------------------------------------------------------------------------- |
167 | /// @return The main Dart entrypoint to be used for the root isolate. |
168 | /// |
169 | const std::string& GetEntrypoint() const; |
170 | |
171 | //---------------------------------------------------------------------------- |
172 | /// @return The name of the library in which the main entrypoint resides. |
173 | /// If empty, the root library is used. |
174 | /// |
175 | const std::string& GetEntrypointLibrary() const; |
176 | |
177 | //---------------------------------------------------------------------------- |
178 | /// @return Arguments passed as a List<String> to Dart's entrypoint |
179 | /// function. |
180 | /// |
181 | const std::vector<std::string>& GetEntrypointArgs() const; |
182 | |
183 | //---------------------------------------------------------------------------- |
184 | /// @brief The engine uses this to take the isolate configuration from |
185 | /// the run configuration. The run configuration is no longer |
186 | /// valid after this call is made. The non-copyable nature of some |
187 | /// of the snapshots referenced in the isolate configuration is |
188 | /// why the run configuration as a whole is not copyable. |
189 | /// |
190 | /// @return The run configuration if one is present. |
191 | /// |
192 | std::unique_ptr<IsolateConfiguration> TakeIsolateConfiguration(); |
193 | |
194 | private: |
195 | std::unique_ptr<IsolateConfiguration> isolate_configuration_; |
196 | std::shared_ptr<AssetManager> asset_manager_; |
197 | std::string entrypoint_ = "main" ; |
198 | std::string entrypoint_library_ = "" ; |
199 | std::vector<std::string> entrypoint_args_; |
200 | |
201 | FML_DISALLOW_COPY_AND_ASSIGN(RunConfiguration); |
202 | }; |
203 | |
204 | } // namespace flutter |
205 | |
206 | #endif // FLUTTER_SHELL_COMMON_RUN_CONFIGURATION_H_ |
207 | |