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
19namespace 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///
29class 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

source code of flutter_engine/flutter/shell/common/run_configuration.h