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/shell/common/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 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 | 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 | RunConfiguration(std::unique_ptr<IsolateConfiguration> configuration); |
70 | |
71 | //---------------------------------------------------------------------------- |
72 | /// @brief Creates a run configuration with the specified isolate |
73 | /// configuration and asset manager. The default entrypoint and |
74 | /// root library are used ("main" in root library). |
75 | /// |
76 | /// @param[in] configuration The configuration |
77 | /// @param[in] asset_manager The asset manager |
78 | /// |
79 | RunConfiguration(std::unique_ptr<IsolateConfiguration> configuration, |
80 | std::shared_ptr<AssetManager> asset_manager); |
81 | |
82 | //---------------------------------------------------------------------------- |
83 | /// @brief Run configurations cannot be copied because it may not always |
84 | /// be possible to copy the underlying isolate snapshots. If |
85 | /// multiple run configurations share the same underlying |
86 | /// snapshots, creating a configuration from isolate snapshots |
87 | /// sharing the same underlying buffers is recommended. |
88 | /// |
89 | /// @param config The run configuration to move. |
90 | /// |
91 | RunConfiguration(RunConfiguration&& config); |
92 | |
93 | //---------------------------------------------------------------------------- |
94 | /// @brief There are no threading restrictions on the destruction of the |
95 | /// run configuration. |
96 | /// |
97 | ~RunConfiguration(); |
98 | |
99 | //---------------------------------------------------------------------------- |
100 | /// @brief A valid run configuration only guarantees that the engine |
101 | /// should be able to find the assets and the isolate snapshots |
102 | /// when it attempts to launch the root isolate. The validity of |
103 | /// the snapshot cannot be determined yet. That determination can |
104 | /// only be made when the configuration is used to run the root |
105 | /// isolate in the engine. However, the engine will always reject |
106 | /// an invalid run configuration. |
107 | /// |
108 | /// @attention A valid run configuration does not mean that the root isolate |
109 | /// will always be launched. It only indicates that the various |
110 | /// snapshots are isolate snapshots and asset managers are present |
111 | /// and accounted for. The validity of the snapshots will only be |
112 | /// checked when the engine attempts to launch the root isolate. |
113 | /// |
114 | /// @return Returns whether the snapshots and asset manager registrations |
115 | /// are valid. |
116 | /// |
117 | bool IsValid() const; |
118 | |
119 | //---------------------------------------------------------------------------- |
120 | /// @brief Asset managers maintain a list of resolvers that are checked |
121 | /// in order when attempting to locate an asset. This method adds |
122 | /// a resolver to the end of the list. |
123 | /// |
124 | /// @param[in] resolver The asset resolver to add to the engine of the list |
125 | /// resolvers maintained by the asset manager. |
126 | /// |
127 | /// @return Returns whether the resolver was successfully registered. The |
128 | /// resolver must be valid for its registration to be successful. |
129 | /// |
130 | bool AddAssetResolver(std::unique_ptr<AssetResolver> resolver); |
131 | |
132 | //---------------------------------------------------------------------------- |
133 | /// @brief Updates the main application entrypoint. If this is not set, |
134 | /// the |
135 | /// "main" method is used as the entrypoint. |
136 | /// |
137 | /// @param[in] entrypoint The entrypoint to use. |
138 | void SetEntrypoint(std::string entrypoint); |
139 | |
140 | //---------------------------------------------------------------------------- |
141 | /// @brief Specifies the main Dart entrypoint and the library to find |
142 | /// that entrypoint in. By default, this is the "main" method in |
143 | /// the root library. The root library may be specified by |
144 | /// entering the empty string as the second argument. |
145 | /// |
146 | /// @see SetEntrypoint() |
147 | /// |
148 | /// @param[in] entrypoint The entrypoint |
149 | /// @param[in] library The library |
150 | /// |
151 | void SetEntrypointAndLibrary(std::string entrypoint, std::string library); |
152 | |
153 | //---------------------------------------------------------------------------- |
154 | /// @return The asset manager referencing all previously registered asset |
155 | /// resolvers. |
156 | /// |
157 | std::shared_ptr<AssetManager> GetAssetManager() const; |
158 | |
159 | //---------------------------------------------------------------------------- |
160 | /// @return The main Dart entrypoint to be used for the root isolate. |
161 | /// |
162 | const std::string& GetEntrypoint() const; |
163 | |
164 | //---------------------------------------------------------------------------- |
165 | /// @return The name of the library in which the main entrypoint resides. |
166 | /// If empty, the root library is used. |
167 | /// |
168 | const std::string& GetEntrypointLibrary() const; |
169 | |
170 | //---------------------------------------------------------------------------- |
171 | /// @brief The engine uses this to take the isolate configuration from |
172 | /// the run configuration. The run configuration is no longer |
173 | /// valid after this call is made. The non-copyable nature of some |
174 | /// of the snapshots referenced in the isolate configuration is |
175 | /// why the run configuration as a whole is not copyable. |
176 | /// |
177 | /// @return The run configuration if one is present. |
178 | /// |
179 | std::unique_ptr<IsolateConfiguration> TakeIsolateConfiguration(); |
180 | |
181 | private: |
182 | std::unique_ptr<IsolateConfiguration> isolate_configuration_; |
183 | std::shared_ptr<AssetManager> asset_manager_; |
184 | std::string entrypoint_ = "main" ; |
185 | std::string entrypoint_library_ = "" ; |
186 | |
187 | FML_DISALLOW_COPY_AND_ASSIGN(RunConfiguration); |
188 | }; |
189 | |
190 | } // namespace flutter |
191 | |
192 | #endif // FLUTTER_SHELL_COMMON_RUN_CONFIGURATION_H_ |
193 | |