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#include <stdint.h>
10
11#include <chrono>
12#include <memory>
13#include <string>
14#include <vector>
15
16#include "flutter/fml/closure.h"
17#include "flutter/fml/mapping.h"
18#include "flutter/fml/time/time_point.h"
19#include "flutter/fml/unique_fd.h"
20
21namespace flutter {
22
23class FrameTiming {
24 public:
25 enum Phase {
26 kVsyncStart,
27 kBuildStart,
28 kBuildFinish,
29 kRasterStart,
30 kRasterFinish,
31 kCount
32 };
33
34 static constexpr Phase kPhases[kCount] = {
35 kVsyncStart, kBuildStart, kBuildFinish, kRasterStart, kRasterFinish};
36
37 fml::TimePoint Get(Phase phase) const { return data_[phase]; }
38 fml::TimePoint Set(Phase phase, fml::TimePoint value) {
39 return data_[phase] = value;
40 }
41
42 private:
43 fml::TimePoint data_[kCount];
44};
45
46using TaskObserverAdd =
47 std::function<void(intptr_t /* key */, fml::closure /* callback */)>;
48using TaskObserverRemove = std::function<void(intptr_t /* key */)>;
49using UnhandledExceptionCallback =
50 std::function<bool(const std::string& /* error */,
51 const std::string& /* stack trace */)>;
52
53// TODO(chinmaygarde): Deprecate all the "path" struct members in favor of the
54// callback that generates the mapping from these paths.
55// https://github.com/flutter/flutter/issues/26783
56using MappingCallback = std::function<std::unique_ptr<fml::Mapping>(void)>;
57using MappingsCallback =
58 std::function<std::vector<std::unique_ptr<const fml::Mapping>>(void)>;
59
60using FrameRasterizedCallback = std::function<void(const FrameTiming&)>;
61
62struct Settings {
63 Settings();
64
65 Settings(const Settings& other);
66
67 ~Settings();
68
69 // VM settings
70 std::string vm_snapshot_data_path; // deprecated
71 MappingCallback vm_snapshot_data;
72 std::string vm_snapshot_instr_path; // deprecated
73 MappingCallback vm_snapshot_instr;
74
75 std::string isolate_snapshot_data_path; // deprecated
76 MappingCallback isolate_snapshot_data;
77 std::string isolate_snapshot_instr_path; // deprecated
78 MappingCallback isolate_snapshot_instr;
79
80 // Returns the Mapping to a kernel buffer which contains sources for dart:*
81 // libraries.
82 MappingCallback dart_library_sources_kernel;
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
91 MappingsCallback application_kernels;
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.
115 std::string 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 // The IP address to which the Dart VM service is bound.
130 std::string observatory_host;
131
132 // The port to which the Dart VM service is bound. When set to `0`, a free
133 // port will be automatically selected by the OS. A message is logged on the
134 // target indicating the URL at which the VM service can be accessed.
135 uint32_t observatory_port = 0;
136
137 // Determines whether an authentication code is required to communicate with
138 // the VM service.
139 bool disable_service_auth_codes = true;
140
141 // Determine whether the vmservice should fallback to automatic port selection
142 // after failing to bind to a specified port.
143 bool enable_service_port_fallback = false;
144
145 // Font settings
146 bool use_test_fonts = false;
147
148 // All shells in the process share the same VM. The last shell to shutdown
149 // should typically shut down the VM as well. However, applications depend on
150 // the behavior of "warming-up" the VM by creating a shell that does not do
151 // anything. This used to work earlier when the VM could not be shut down (and
152 // hence never was). Shutting down the VM now breaks such assumptions in
153 // existing embedders. To keep this behavior consistent and allow existing
154 // embedders the chance to migrate, this flag defaults to true. Any shell
155 // launched with this flag set to true will leak the VM in the process. There
156 // is no way to shut down the VM once such a shell has been started. All
157 // shells in the platform (via their embedding APIs) should cooperate to make
158 // sure this flag is never set if they want the VM to shutdown and free all
159 // associated resources.
160 bool leak_vm = true;
161
162 // Engine settings
163 TaskObserverAdd task_observer_add;
164 TaskObserverRemove task_observer_remove;
165 // The main isolate is current when this callback is made. This is a good spot
166 // to perform native Dart bindings for libraries not built in.
167 fml::closure root_isolate_create_callback;
168 fml::closure isolate_create_callback;
169 // The isolate is not current and may have already been destroyed when this
170 // call is made.
171 fml::closure root_isolate_shutdown_callback;
172 fml::closure isolate_shutdown_callback;
173 // The callback made on the UI thread in an isolate scope when the engine
174 // detects that the framework is idle. The VM also uses this time to perform
175 // tasks suitable when idling. Due to this, embedders are still advised to be
176 // as fast as possible in returning from this callback. Long running
177 // operations in this callback do have the capability of introducing jank.
178 std::function<void(int64_t)> idle_notification_callback;
179 // A callback given to the embedder to react to unhandled exceptions in the
180 // running Flutter application. This callback is made on an internal engine
181 // managed thread and embedders must re-thread as necessary. Performing
182 // blocking calls in this callback will cause applications to jank.
183 UnhandledExceptionCallback unhandled_exception_callback;
184 bool enable_software_rendering = false;
185 bool skia_deterministic_rendering_on_cpu = false;
186 bool verbose_logging = false;
187 std::string log_tag = "flutter";
188
189 // The icu_initialization_required setting does not have a corresponding
190 // switch because it is intended to be decided during build time, not runtime.
191 // Some companies apply source modification here because their build system
192 // brings its own ICU data files.
193 bool icu_initialization_required = true;
194 std::string icu_data_path;
195 MappingCallback icu_mapper;
196
197 // Assets settings
198 fml::UniqueFD::element_type assets_dir =
199 fml::UniqueFD::traits_type::InvalidValue();
200 std::string assets_path;
201
202 // Callback to handle the timings of a rasterized frame. This is called as
203 // soon as a frame is rasterized.
204 FrameRasterizedCallback frame_rasterized_callback;
205
206 // This data will be available to the isolate immediately on launch via the
207 // Window.getPersistentIsolateData callback. This is meant for information
208 // that the isolate cannot request asynchronously (platform messages can be
209 // used for that purpose). This data is held for the lifetime of the shell and
210 // is available on isolate restarts in the shell instance. Due to this,
211 // the buffer must be as small as possible.
212 std::shared_ptr<const fml::Mapping> persistent_isolate_data;
213
214 /// Max size of old gen heap size in MB, or 0 for unlimited, -1 for default
215 /// value.
216 ///
217 /// See also:
218 /// https://github.com/dart-lang/sdk/blob/ca64509108b3e7219c50d6c52877c85ab6a35ff2/runtime/vm/flag_list.h#L150
219 int64_t old_gen_heap_size = -1;
220
221 /// A timestamp representing when the engine started. The value is based
222 /// on the clock used by the Dart timeline APIs. This timestamp is used
223 /// to log a timeline event that tracks the latency of engine startup.
224 std::chrono::microseconds engine_start_timestamp = {};
225
226 /// Whether the application claims that it uses the android embedded view for
227 /// platform views.
228 ///
229 /// A `true` value will result the raster task runner always run on the
230 /// platform thread.
231 // TODO(cyanlaz): Remove this when dynamic thread merging is done.
232 // https://github.com/flutter/flutter/issues/59930
233 bool use_embedded_view = false;
234
235 std::string ToString() const;
236};
237
238} // namespace flutter
239
240#endif // FLUTTER_COMMON_SETTINGS_H_
241