Flutter Engine
run_configuration.h
Go to the documentation of this file.
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 ///
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  ///
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  ///
92 
93  //----------------------------------------------------------------------------
94  /// @brief There are no threading restrictions on the destruction of the
95  /// run configuration.
96  ///
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_
bool IsValid() const
A valid run configuration only guarantees that the engine should be able to find the assets and the i...
std::shared_ptr< AssetManager > GetAssetManager() const
std::unique_ptr< IsolateConfiguration > TakeIsolateConfiguration()
The engine uses this to take the isolate configuration from the run configuration. The run configuration is no longer valid after this call is made. The non-copyable nature of some of the snapshots referenced in the isolate configuration is why the run configuration as a whole is not copyable.
const std::string & GetEntrypoint() const
RunConfiguration(std::unique_ptr< IsolateConfiguration > configuration)
Creates a run configuration with only an isolate configuration. There is no asset manager and default...
const std::string & GetEntrypointLibrary() const
~RunConfiguration()
There are no threading restrictions on the destruction of the run configuration.
void SetEntrypoint(std::string entrypoint)
Updates the main application entrypoint. If this is not set, the "main" method is used as the entrypo...
static RunConfiguration InferFromSettings(const Settings &settings, fml::RefPtr< fml::TaskRunner > io_worker=nullptr)
Attempts to infer a run configuration from the settings object. This tries to create a run configurat...
Specifies all the configuration required by the runtime library to launch the root isolate...
void SetEntrypointAndLibrary(std::string entrypoint, std::string library)
Specifies the main Dart entrypoint and the library to find that entrypoint in. By default...
bool AddAssetResolver(std::unique_ptr< AssetResolver > resolver)
Asset managers maintain a list of resolvers that are checked in order when attempting to locate an as...