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
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 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