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/common/settings.h" 12 #include "flutter/fml/macros.h" 13 #include "flutter/fml/mapping.h" 14 #include "flutter/fml/task_runner.h" 15 #include "flutter/fml/unique_fd.h" 16 #include "flutter/shell/common/rasterizer.h" 17 18 namespace flutter { 19 20 //------------------------------------------------------------------------------ 21 /// @brief Specifies all the configuration required by the runtime library 22 /// to launch the root isolate. This object may be created on any 23 /// thread but must be given to the |Run| call of the |Engine| on 24 /// the UI thread. The configuration object is used to specify how 25 /// the root isolate finds its snapshots, assets, root library and 26 /// the "main" entrypoint. 27 /// 28 class RunConfiguration { 29 public: 30 //---------------------------------------------------------------------------- 31 /// @brief Attempts to infer a run configuration from the settings 32 /// object. This tries to create a run configuration with sensible 33 /// defaults for the given Dart VM runtime mode. In JIT mode, this 34 /// will attempt to look for the VM and isolate snapshots in the 35 /// assets directory (must be specified in settings). In AOT mode, 36 /// it will attempt to look for known snapshot symbols in the 37 /// currently currently loaded process. The entrypoint defaults to 38 /// the "main" method in the root library. 39 /// 40 /// @param[in] settings The settings object used to look for the various 41 /// snapshots and settings. This is usually initialized 42 /// from command line arguments. 43 /// @param[in] io_worker An optional IO worker. Resolving and reading the 44 /// various snapshots may be slow. Providing an IO 45 /// worker will ensure that realization of these 46 /// snapshots happens on a worker thread instead of the 47 /// calling thread. Note that the work done to realize 48 /// the snapshots may occur after this call returns. If 49 /// is the embedder's responsibility to make sure the 50 /// serial worker is kept alive for the lifetime of the 51 /// shell associated with the engine that this run 52 /// configuration is given to. 53 /// 54 /// @return A run configuration. Depending on the completeness of the 55 /// settings, This object may potentially be invalid. 56 /// 57 static RunConfiguration InferFromSettings( 58 const Settings& settings, 59 fml::RefPtr<fml::TaskRunner> io_worker = nullptr); 60 61 RunConfiguration() = default; 62 63 //---------------------------------------------------------------------------- 64 /// @brief Run configurations cannot be copied because it may not always 65 /// be possible to copy the underlying isolate snapshots. If 66 /// multiple run configurations share the same underlying 67 /// snapshots, creating a configuration from isolate snapshots 68 /// sharing the same underlying buffers is recommended. 69 /// 70 /// @param config The run configuration to move. 71 /// 72 RunConfiguration(RunConfiguration&& config); 73 74 //---------------------------------------------------------------------------- 75 /// @brief There are no threading restrictions on the destruction of the 76 /// run configuration. 77 /// 78 ~RunConfiguration(); 79 80 //---------------------------------------------------------------------------- 81 /// @brief A valid run configuration only guarantees that the engine 82 /// should be able to find the assets and the isolate snapshots 83 /// when it attempts to launch the root isolate. The validity of 84 /// the snapshot cannot be determined yet. That determination can 85 /// only be made when the configuration is used to run the root 86 /// isolate in the engine. However, the engine will always reject 87 /// an invalid run configuration. 88 /// 89 /// @attention A valid run configuration does not mean that the root isolate 90 /// will always be launched. It only indicates that the various 91 /// snapshots are isolate snapshots and asset managers are present 92 /// and accounted for. The validity of the snapshots will only be 93 /// checked when the engine attempts to launch the root isolate. 94 /// 95 /// @return Returns whether the snapshots and asset manager registrations 96 /// are valid. 97 /// 98 bool IsValid() const; 99 100 //---------------------------------------------------------------------------- 101 /// @brief Updates the main application entrypoint. If this is not set, 102 /// the 103 /// "main" method is used as the entrypoint. 104 /// 105 /// @param[in] entrypoint The entrypoint to use. 106 void SetEntrypoint(std::string entrypoint); 107 108 //---------------------------------------------------------------------------- 109 /// @brief Specifies the main Dart entrypoint and the library to find 110 /// that entrypoint in. By default, this is the "main" method in 111 /// the root library. The root library may be specified by 112 /// entering the empty string as the second argument. 113 /// 114 /// @see SetEntrypoint() 115 /// 116 /// @param[in] entrypoint The entrypoint 117 /// @param[in] library The library 118 /// 119 void SetEntrypointAndLibrary(std::string entrypoint, std::string library); 120 121 //---------------------------------------------------------------------------- 122 /// @return The main Dart entrypoint to be used for the root isolate. 123 /// 124 const std::string& GetEntrypoint() const; 125 126 //---------------------------------------------------------------------------- 127 /// @return The name of the library in which the main entrypoint resides. 128 /// If empty, the root library is used. 129 /// 130 const std::string& GetEntrypointLibrary() const; 131 132 private: 133 std::string entrypoint_ = "main"; 134 std::string entrypoint_library_ = ""; 135 136 FML_DISALLOW_COPY_AND_ASSIGN(RunConfiguration); 137 }; 138 139 } // namespace flutter 140 141 #endif // FLUTTER_SHELL_COMMON_RUN_CONFIGURATION_H_ 142