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 | |
21 | namespace flutter { |
22 | |
23 | class 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 | |
46 | using TaskObserverAdd = |
47 | std::function<void(intptr_t /* key */, fml::closure /* callback */)>; |
48 | using TaskObserverRemove = std::function<void(intptr_t /* key */)>; |
49 | using 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 |
56 | using MappingCallback = std::function<std::unique_ptr<fml::Mapping>(void)>; |
57 | using MappingsCallback = |
58 | std::function<std::vector<std::unique_ptr<const fml::Mapping>>(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 |
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 | |