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