Flutter Engine
settings.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_COMMON_SETTINGS_H_
6 #define FLUTTER_COMMON_SETTINGS_H_
7 
8 #include <fcntl.h>
9 
10 #include <chrono>
11 #include <cstdint>
12 #include <memory>
13 #include <optional>
14 #include <string>
15 #include <vector>
16 
17 #include "flutter/fml/closure.h"
18 #include "flutter/fml/mapping.h"
19 #include "flutter/fml/time/time_point.h"
20 #include "flutter/fml/unique_fd.h"
21 
22 namespace flutter {
23 
24 class FrameTiming {
25  public:
26  enum Phase {
33  };
34 
35  static constexpr Phase kPhases[kCount] = {
37 
38  fml::TimePoint Get(Phase phase) const { return data_[phase]; }
40  return data_[phase] = value;
41  }
42 
43  private:
44  fml::TimePoint data_[kCount];
45 };
46 
47 using TaskObserverAdd =
48  std::function<void(intptr_t /* key */, fml::closure /* callback */)>;
49 using TaskObserverRemove = std::function<void(intptr_t /* key */)>;
51  std::function<bool(const std::string& /* error */,
52  const std::string& /* stack trace */)>;
53 
54 // TODO(26783): Deprecate all the "path" struct members in favor of the
55 // callback that generates the mapping from these paths.
56 using MappingCallback = std::function<std::unique_ptr<fml::Mapping>(void)>;
57 using Mappings = std::vector<std::unique_ptr<const fml::Mapping>>;
58 using MappingsCallback = std::function<Mappings(void)>;
59 
60 using FrameRasterizedCallback = std::function<void(const FrameTiming&)>;
61 
62 struct Settings {
63  Settings();
64 
65  Settings(const Settings& other);
66 
67  ~Settings();
68 
69  // VM settings
70  std::string vm_snapshot_data_path; // deprecated
72  std::string vm_snapshot_instr_path; // deprecated
74 
75  std::string isolate_snapshot_data_path; // deprecated
77  std::string isolate_snapshot_instr_path; // deprecated
79 
80  // Returns the Mapping to a kernel buffer which contains sources for dart:*
81  // libraries.
83 
84  // Path to a library containing the application's compiled Dart code.
85  // This is a vector so that the embedder can provide fallback paths in
86  // case the primary path to the library can not be loaded.
87  std::vector<std::string> application_library_path;
88 
89  std::string application_kernel_asset; // deprecated
90  std::string application_kernel_list_asset; // deprecated
92 
93  std::string temp_directory_path;
94  std::vector<std::string> dart_flags;
95  // Arguments passed as a List<String> to Dart's entrypoint function.
96  std::vector<std::string> dart_entrypoint_args;
97 
98  // Isolate settings
99  bool enable_checked_mode = false;
100  bool start_paused = false;
101  bool trace_skia = false;
102  std::string trace_allowlist;
103  bool trace_startup = false;
104  bool trace_systrace = false;
105  bool dump_skp_on_shader_compilation = false;
106  bool cache_sksl = false;
107  bool purge_persistent_cache = false;
108  bool endless_trace_buffer = false;
109  bool enable_dart_profiling = false;
110  bool disable_dart_asserts = false;
111 
112  // Whether embedder only allows secure connections.
113  bool may_insecurely_connect_to_all_domains = true;
114  // JSON-formatted domain network policy.
116 
117  // Used as the script URI in debug messages. Does not affect how the Dart code
118  // is executed.
119  std::string advisory_script_uri = "main.dart";
120  // Used as the script entrypoint in debug messages. Does not affect how the
121  // Dart code is executed.
122  std::string advisory_script_entrypoint = "main";
123 
124  // Observatory settings
125 
126  // Whether the Dart VM service should be enabled.
127  bool enable_observatory = false;
128 
129  // Whether to publish the observatory URL over mDNS.
130  // On iOS 14 this prompts a local network permission dialog,
131  // which cannot be accepted or dismissed in a CI environment.
132  bool enable_observatory_publication = true;
133 
134  // The IP address to which the Dart VM service is bound.
135  std::string observatory_host;
136 
137  // The port to which the Dart VM service is bound. When set to `0`, a free
138  // port will be automatically selected by the OS. A message is logged on the
139  // target indicating the URL at which the VM service can be accessed.
140  uint32_t observatory_port = 0;
141 
142  // Determines whether an authentication code is required to communicate with
143  // the VM service.
144  bool disable_service_auth_codes = true;
145 
146  // Determine whether the vmservice should fallback to automatic port selection
147  // after failing to bind to a specified port.
148  bool enable_service_port_fallback = false;
149 
150  // Font settings
151  bool use_test_fonts = false;
152 
153  // All shells in the process share the same VM. The last shell to shutdown
154  // should typically shut down the VM as well. However, applications depend on
155  // the behavior of "warming-up" the VM by creating a shell that does not do
156  // anything. This used to work earlier when the VM could not be shut down (and
157  // hence never was). Shutting down the VM now breaks such assumptions in
158  // existing embedders. To keep this behavior consistent and allow existing
159  // embedders the chance to migrate, this flag defaults to true. Any shell
160  // launched with this flag set to true will leak the VM in the process. There
161  // is no way to shut down the VM once such a shell has been started. All
162  // shells in the platform (via their embedding APIs) should cooperate to make
163  // sure this flag is never set if they want the VM to shutdown and free all
164  // associated resources.
165  bool leak_vm = true;
166 
167  // Engine settings
170  // The main isolate is current when this callback is made. This is a good spot
171  // to perform native Dart bindings for libraries not built in.
174  // The isolate is not current and may have already been destroyed when this
175  // call is made.
178  // A callback made in the isolate scope of the service isolate when it is
179  // launched. Care must be taken to ensure that callers are assigning callbacks
180  // to the settings object used to launch the VM. If an existing VM is used to
181  // launch an isolate using these settings, the callback will be ignored as the
182  // service isolate has already been launched. Also, this callback will only be
183  // made in the modes in which the service isolate is eligible for launch
184  // (debug and profile).
186  // The callback made on the UI thread in an isolate scope when the engine
187  // detects that the framework is idle. The VM also uses this time to perform
188  // tasks suitable when idling. Due to this, embedders are still advised to be
189  // as fast as possible in returning from this callback. Long running
190  // operations in this callback do have the capability of introducing jank.
191  std::function<void(int64_t)> idle_notification_callback;
192  // A callback given to the embedder to react to unhandled exceptions in the
193  // running Flutter application. This callback is made on an internal engine
194  // managed thread and embedders must re-thread as necessary. Performing
195  // blocking calls in this callback will cause applications to jank.
197  bool enable_software_rendering = false;
198  bool skia_deterministic_rendering_on_cpu = false;
199  bool verbose_logging = false;
200  std::string log_tag = "flutter";
201 
202  // The icu_initialization_required setting does not have a corresponding
203  // switch because it is intended to be decided during build time, not runtime.
204  // Some companies apply source modification here because their build system
205  // brings its own ICU data files.
206  bool icu_initialization_required = true;
207  std::string icu_data_path;
209 
210  // Assets settings
213  std::string assets_path;
214 
215  // Callback to handle the timings of a rasterized frame. This is called as
216  // soon as a frame is rasterized.
218 
219  // This data will be available to the isolate immediately on launch via the
220  // Window.getPersistentIsolateData callback. This is meant for information
221  // that the isolate cannot request asynchronously (platform messages can be
222  // used for that purpose). This data is held for the lifetime of the shell and
223  // is available on isolate restarts in the shell instance. Due to this,
224  // the buffer must be as small as possible.
225  std::shared_ptr<const fml::Mapping> persistent_isolate_data;
226 
227  /// Max size of old gen heap size in MB, or 0 for unlimited, -1 for default
228  /// value.
229  ///
230  /// See also:
231  /// https://github.com/dart-lang/sdk/blob/ca64509108b3e7219c50d6c52877c85ab6a35ff2/runtime/vm/flag_list.h#L150
232  int64_t old_gen_heap_size = -1;
233 
234  /// A timestamp representing when the engine started. The value is based
235  /// on the clock used by the Dart timeline APIs. This timestamp is used
236  /// to log a timeline event that tracks the latency of engine startup.
237  std::chrono::microseconds engine_start_timestamp = {};
238 
239  std::string ToString() const;
240 };
241 
242 } // namespace flutter
243 
244 #endif // FLUTTER_COMMON_SETTINGS_H_
std::function< bool(const std::string &, const std::string &)> UnhandledExceptionCallback
Definition: settings.h:52
MappingCallback isolate_snapshot_instr
Definition: settings.h:78
std::function< std::unique_ptr< fml::Mapping >(void)> MappingCallback
Definition: settings.h:56
fml::closure isolate_shutdown_callback
Definition: settings.h:177
std::function< Mappings(void)> MappingsCallback
Definition: settings.h:58
std::string application_kernel_list_asset
Definition: settings.h:90
MappingsCallback application_kernels
Definition: settings.h:91
std::vector< std::string > dart_entrypoint_args
Definition: settings.h:96
std::function< void(const FrameTiming &)> FrameRasterizedCallback
Definition: settings.h:60
std::function< void(intptr_t)> TaskObserverRemove
Definition: settings.h:49
std::string application_kernel_asset
Definition: settings.h:89
std::string trace_allowlist
Definition: settings.h:102
fml::closure isolate_create_callback
Definition: settings.h:173
std::string temp_directory_path
Definition: settings.h:93
std::string isolate_snapshot_instr_path
Definition: settings.h:77
fml::TimePoint Set(Phase phase, fml::TimePoint value)
Definition: settings.h:39
MappingCallback vm_snapshot_data
Definition: settings.h:71
Dart_NativeFunction function
Definition: fuchsia.cc:51
fml::closure service_isolate_create_callback
Definition: settings.h:185
std::string isolate_snapshot_data_path
Definition: settings.h:75
std::vector< std::unique_ptr< const fml::Mapping > > Mappings
Definition: settings.h:57
static constexpr Phase kPhases[kCount]
Definition: settings.h:35
UnhandledExceptionCallback unhandled_exception_callback
Definition: settings.h:196
std::function< void()> closure
Definition: closure.h:14
fml::closure root_isolate_shutdown_callback
Definition: settings.h:176
uint8_t value
std::function< void(intptr_t, fml::closure)> TaskObserverAdd
Definition: settings.h:48
fml::closure root_isolate_create_callback
Definition: settings.h:172
std::string domain_network_policy
Definition: settings.h:115
FlutterPointerPhase phase
Definition: fl_view.cc:78
std::string observatory_host
Definition: settings.h:135
TaskObserverAdd task_observer_add
Definition: settings.h:168
std::vector< std::string > dart_flags
Definition: settings.h:94
std::string icu_data_path
Definition: settings.h:207
MappingCallback isolate_snapshot_data
Definition: settings.h:76
std::vector< std::string > application_library_path
Definition: settings.h:87
MappingCallback dart_library_sources_kernel
Definition: settings.h:82
std::string vm_snapshot_data_path
Definition: settings.h:70
fml::TimePoint Get(Phase phase) const
Definition: settings.h:38
MappingCallback vm_snapshot_instr
Definition: settings.h:73
std::shared_ptr< const fml::Mapping > persistent_isolate_data
Definition: settings.h:225
MappingCallback icu_mapper
Definition: settings.h:208
TaskObserverRemove task_observer_remove
Definition: settings.h:169
std::string vm_snapshot_instr_path
Definition: settings.h:72
std::string assets_path
Definition: settings.h:213
FrameRasterizedCallback frame_rasterized_callback
Definition: settings.h:217
std::function< void(int64_t)> idle_notification_callback
Definition: settings.h:191