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 SHELL_COMMON_SHELL_H_
6#define SHELL_COMMON_SHELL_H_
7
8#include <functional>
9#include <mutex>
10#include <string_view>
11#include <unordered_map>
12
13#include "flutter/common/settings.h"
14#include "flutter/common/task_runners.h"
15#include "flutter/flow/surface.h"
16#include "flutter/flow/texture.h"
17#include "flutter/fml/closure.h"
18#include "flutter/fml/macros.h"
19#include "flutter/fml/memory/ref_ptr.h"
20#include "flutter/fml/memory/thread_checker.h"
21#include "flutter/fml/memory/weak_ptr.h"
22#include "flutter/fml/status.h"
23#include "flutter/fml/synchronization/sync_switch.h"
24#include "flutter/fml/synchronization/waitable_event.h"
25#include "flutter/fml/thread.h"
26#include "flutter/fml/time/time_point.h"
27#include "flutter/lib/ui/semantics/custom_accessibility_action.h"
28#include "flutter/lib/ui/semantics/semantics_node.h"
29#include "flutter/lib/ui/window/platform_message.h"
30#include "flutter/runtime/dart_vm_lifecycle.h"
31#include "flutter/runtime/service_protocol.h"
32#include "flutter/shell/common/animator.h"
33#include "flutter/shell/common/engine.h"
34#include "flutter/shell/common/platform_view.h"
35#include "flutter/shell/common/rasterizer.h"
36#include "flutter/shell/common/shell_io_manager.h"
37
38namespace flutter {
39
40/// Error exit codes for the Dart isolate.
41enum class DartErrorCode {
42 /// No error has occurred.
43 NoError = 0,
44 /// The Dart error code for an API error.
45 ApiError = 253,
46 /// The Dart error code for a compilation error.
47 CompilationError = 254,
48 /// The Dart error code for an unkonwn error.
49 UnknownError = 255
50};
51
52//------------------------------------------------------------------------------
53/// Perhaps the single most important class in the Flutter engine repository.
54/// When embedders create a Flutter application, they are referring to the
55/// creation of an instance of a shell. Creation and destruction of the shell is
56/// synchronous and the embedder only holds a unique pointer to the shell. The
57/// shell does not create the threads its primary components run on. Instead, it
58/// is the embedder's responsibility to create threads and give the shell task
59/// runners for those threads. Due to deterministic destruction of the shell,
60/// the embedder can terminate all threads immediately after collecting the
61/// shell. The shell must be created and destroyed on the same thread, but,
62/// different shells (i.e. a separate instances of a Flutter application) may be
63/// run on different threads simultaneously. The task runners themselves do not
64/// have to be unique. If all task runner references given to the shell during
65/// shell creation point to the same task runner, the Flutter application is
66/// effectively single threaded.
67///
68/// The shell is the central nervous system of the Flutter application. None of
69/// the shell components are thread safe and must be created, accessed and
70/// destroyed on the same thread. To interact with one another, the various
71/// components delegate to the shell for communication. Instead of using back
72/// pointers to the shell, a delegation pattern is used by all components that
73/// want to communicate with one another. Because of this, the shell implements
74/// the delegate interface for all these components.
75///
76/// All shell methods accessed by the embedder may only be called on the
77/// platform task runner. In case the embedder wants to directly access a shell
78/// subcomponent, it is the embedder's responsibility to acquire a weak pointer
79/// to that component and post a task to the task runner used by the component
80/// to access its methods. The shell must also be destroyed on the platform
81/// task runner.
82///
83/// There is no explicit API to bootstrap and shutdown the Dart VM. The first
84/// instance of the shell in the process bootstraps the Dart VM and the
85/// destruction of the last shell instance destroys the same. Since different
86/// shells may be created and destroyed on different threads. VM bootstrap may
87/// happen on one thread but its collection on another. This behavior is thread
88/// safe.
89///
90class Shell final : public PlatformView::Delegate,
91 public Animator::Delegate,
92 public Engine::Delegate,
93 public Rasterizer::Delegate,
94 public ServiceProtocol::Handler {
95 public:
96 template <class T>
97 using CreateCallback = std::function<std::unique_ptr<T>(Shell&)>;
98
99 //----------------------------------------------------------------------------
100 /// @brief Creates a shell instance using the provided settings. The
101 /// callbacks to create the various shell subcomponents will be
102 /// called on the appropriate threads before this method returns.
103 /// If this is the first instance of a shell in the process, this
104 /// call also bootstraps the Dart VM.
105 ///
106 /// @param[in] task_runners The task runners
107 /// @param[in] settings The settings
108 /// @param[in] on_create_platform_view The callback that must return a
109 /// platform view. This will be called on
110 /// the platform task runner before this
111 /// method returns.
112 /// @param[in] on_create_rasterizer That callback that must provide a
113 /// valid rasterizer. This will be called
114 /// on the render task runner before this
115 /// method returns.
116 ///
117 /// @return A full initialized shell if the settings and callbacks are
118 /// valid. The root isolate has been created but not yet launched.
119 /// It may be launched by obtaining the engine weak pointer and
120 /// posting a task onto the UI task runner with a valid run
121 /// configuration to run the isolate. The embedder must always
122 /// check the validity of the shell (using the IsSetup call)
123 /// immediately after getting a pointer to it.
124 ///
125 static std::unique_ptr<Shell> Create(
126 TaskRunners task_runners,
127 Settings settings,
128 const CreateCallback<PlatformView>& on_create_platform_view,
129 const CreateCallback<Rasterizer>& on_create_rasterizer);
130
131 //----------------------------------------------------------------------------
132 /// @brief Creates a shell instance using the provided settings. The
133 /// callbacks to create the various shell subcomponents will be
134 /// called on the appropriate threads before this method returns.
135 /// Unlike the simpler variant of this factory method, this method
136 /// allows for specification of window data. If this is the first
137 /// instance of a shell in the process, this call also bootstraps
138 /// the Dart VM.
139 ///
140 /// @param[in] task_runners The task runners
141 /// @param[in] platform_data The default data for setting up
142 /// ui.Window that attached to this
143 /// intance.
144 /// @param[in] settings The settings
145 /// @param[in] on_create_platform_view The callback that must return a
146 /// platform view. This will be called on
147 /// the platform task runner before this
148 /// method returns.
149 /// @param[in] on_create_rasterizer That callback that must provide a
150 /// valid rasterizer. This will be called
151 /// on the render task runner before this
152 /// method returns.
153 ///
154 /// @return A full initialized shell if the settings and callbacks are
155 /// valid. The root isolate has been created but not yet launched.
156 /// It may be launched by obtaining the engine weak pointer and
157 /// posting a task onto the UI task runner with a valid run
158 /// configuration to run the isolate. The embedder must always
159 /// check the validity of the shell (using the IsSetup call)
160 /// immediately after getting a pointer to it.
161 ///
162 static std::unique_ptr<Shell> Create(
163 TaskRunners task_runners,
164 const PlatformData platform_data,
165 Settings settings,
166 CreateCallback<PlatformView> on_create_platform_view,
167 CreateCallback<Rasterizer> on_create_rasterizer);
168
169 //----------------------------------------------------------------------------
170 /// @brief Creates a shell instance using the provided settings. The
171 /// callbacks to create the various shell subcomponents will be
172 /// called on the appropriate threads before this method returns.
173 /// Unlike the simpler variant of this factory method, this method
174 /// allows for the specification of an isolate snapshot that
175 /// cannot be adequately described in the settings. This call also
176 /// requires the specification of a running VM instance.
177 ///
178 /// @param[in] task_runners The task runners
179 /// @param[in] platform_data The default data for setting up
180 /// ui.Window that attached to this
181 /// intance.
182 /// @param[in] settings The settings
183 /// @param[in] isolate_snapshot A custom isolate snapshot. Takes
184 /// precedence over any snapshots
185 /// specified in the settings.
186 /// @param[in] on_create_platform_view The callback that must return a
187 /// platform view. This will be called on
188 /// the platform task runner before this
189 /// method returns.
190 /// @param[in] on_create_rasterizer That callback that must provide a
191 /// valid rasterizer. This will be called
192 /// on the render task runner before this
193 /// method returns.
194 /// @param[in] vm A running VM instance.
195 ///
196 /// @return A full initialized shell if the settings and callbacks are
197 /// valid. The root isolate has been created but not yet launched.
198 /// It may be launched by obtaining the engine weak pointer and
199 /// posting a task onto the UI task runner with a valid run
200 /// configuration to run the isolate. The embedder must always
201 /// check the validity of the shell (using the IsSetup call)
202 /// immediately after getting a pointer to it.
203 ///
204 static std::unique_ptr<Shell> Create(
205 TaskRunners task_runners,
206 const PlatformData platform_data,
207 Settings settings,
208 fml::RefPtr<const DartSnapshot> isolate_snapshot,
209 const CreateCallback<PlatformView>& on_create_platform_view,
210 const CreateCallback<Rasterizer>& on_create_rasterizer,
211 DartVMRef vm);
212
213 //----------------------------------------------------------------------------
214 /// @brief Destroys the shell. This is a synchronous operation and
215 /// synchronous barrier blocks are introduced on the various
216 /// threads to ensure shutdown of all shell sub-components before
217 /// this method returns.
218 ///
219 ~Shell();
220
221 //----------------------------------------------------------------------------
222 /// @brief Starts an isolate for the given RunConfiguration.
223 ///
224 void RunEngine(RunConfiguration run_configuration);
225
226 //----------------------------------------------------------------------------
227 /// @brief Starts an isolate for the given RunConfiguration. The
228 /// result_callback will be called with the status of the
229 /// operation.
230 ///
231 void RunEngine(RunConfiguration run_configuration,
232 const std::function<void(Engine::RunStatus)>& result_callback);
233
234 //------------------------------------------------------------------------------
235 /// @return The settings used to launch this shell.
236 ///
237 const Settings& GetSettings() const;
238
239 //------------------------------------------------------------------------------
240 /// @brief If callers wish to interact directly with any shell
241 /// subcomponents, they must (on the platform thread) obtain a
242 /// task runner that the component is designed to run on and a
243 /// weak pointer to that component. They may then post a task to
244 /// that task runner, do the validity check on that task runner
245 /// before performing any operation on that component. This
246 /// accessor allows callers to access the task runners for this
247 /// shell.
248 ///
249 /// @return The task runners current in use by the shell.
250 ///
251 const TaskRunners& GetTaskRunners() const override;
252
253 //----------------------------------------------------------------------------
254 /// @brief Rasterizers may only be accessed on the GPU task runner.
255 ///
256 /// @return A weak pointer to the rasterizer.
257 ///
258 fml::TaskRunnerAffineWeakPtr<Rasterizer> GetRasterizer() const;
259
260 //------------------------------------------------------------------------------
261 /// @brief Engines may only be accessed on the UI thread. This method is
262 /// deprecated, and implementers should instead use other API
263 /// available on the Shell or the PlatformView.
264 ///
265 /// @return A weak pointer to the engine.
266 ///
267 fml::WeakPtr<Engine> GetEngine();
268
269 //----------------------------------------------------------------------------
270 /// @brief Platform views may only be accessed on the platform task
271 /// runner.
272 ///
273 /// @return A weak pointer to the platform view.
274 ///
275 fml::WeakPtr<PlatformView> GetPlatformView();
276
277 // Embedders should call this under low memory conditions to free up
278 // internal caches used.
279 //
280 // This method posts a task to the raster threads to signal the Rasterizer to
281 // free resources.
282
283 //----------------------------------------------------------------------------
284 /// @brief Used by embedders to notify that there is a low memory
285 /// warning. The shell will attempt to purge caches. Current, only
286 /// the rasterizer cache is purged.
287 void NotifyLowMemoryWarning() const;
288
289 //----------------------------------------------------------------------------
290 /// @brief Used by embedders to check if all shell subcomponents are
291 /// initialized. It is the embedder's responsibility to make this
292 /// call before accessing any other shell method. A shell that is
293 /// not setup must be discarded and another one created with
294 /// updated settings.
295 ///
296 /// @return Returns if the shell has been setup. Once set up, this does
297 /// not change for the life-cycle of the shell.
298 ///
299 bool IsSetup() const;
300
301 //----------------------------------------------------------------------------
302 /// @brief Captures a screenshot and optionally Base64 encodes the data
303 /// of the last layer tree rendered by the rasterizer in this
304 /// shell.
305 ///
306 /// @param[in] type The type of screenshot to capture.
307 /// @param[in] base64_encode If the screenshot data should be base64
308 /// encoded.
309 ///
310 /// @return The screenshot result.
311 ///
312 Rasterizer::Screenshot Screenshot(Rasterizer::ScreenshotType type,
313 bool base64_encode);
314
315 //----------------------------------------------------------------------------
316 /// @brief Pauses the calling thread until the first frame is presented.
317 ///
318 /// @return 'kOk' when the first frame has been presented before the timeout
319 /// successfully, 'kFailedPrecondition' if called from the GPU or UI
320 /// thread, 'kDeadlineExceeded' if there is a timeout.
321 ///
322 fml::Status WaitForFirstFrame(fml::TimeDelta timeout);
323
324 //----------------------------------------------------------------------------
325 /// @brief Used by embedders to reload the system fonts in
326 /// FontCollection.
327 /// It also clears the cached font families and send system
328 /// channel message to framework to rebuild affected widgets.
329 ///
330 /// @return Returns if shell reloads system fonts successfully.
331 ///
332 bool ReloadSystemFonts();
333
334 //----------------------------------------------------------------------------
335 /// @brief Used by embedders to get the last error from the Dart UI
336 /// Isolate, if one exists.
337 ///
338 /// @return Returns the last error code from the UI Isolate.
339 ///
340 std::optional<DartErrorCode> GetUIIsolateLastError() const;
341
342 //----------------------------------------------------------------------------
343 /// @brief Used by embedders to check if the Engine is running and has
344 /// any live ports remaining. For example, the Flutter tester uses
345 /// this method to check whether it should continue to wait for
346 /// a running test or not.
347 ///
348 /// @return Returns if the shell has an engine and the engine has any live
349 /// Dart ports.
350 ///
351 bool EngineHasLivePorts() const;
352
353 //----------------------------------------------------------------------------
354 /// @brief Accessor for the disable GPU SyncSwitch
355 std::shared_ptr<fml::SyncSwitch> GetIsGpuDisabledSyncSwitch() const override;
356
357 //----------------------------------------------------------------------------
358 /// @brief Get a pointer to the Dart VM used by this running shell
359 /// instance.
360 ///
361 /// @return The Dart VM pointer.
362 ///
363 DartVM* GetDartVM();
364
365 private:
366 using ServiceProtocolHandler =
367 std::function<bool(const ServiceProtocol::Handler::ServiceProtocolMap&,
368 rapidjson::Document*)>;
369
370 const TaskRunners task_runners_;
371 const Settings settings_;
372 DartVMRef vm_;
373 mutable std::mutex time_recorder_mutex_;
374 std::optional<fml::TimePoint> latest_frame_target_time_;
375 std::unique_ptr<PlatformView> platform_view_; // on platform task runner
376 std::unique_ptr<Engine> engine_; // on UI task runner
377 std::unique_ptr<Rasterizer> rasterizer_; // on GPU task runner
378 std::unique_ptr<ShellIOManager> io_manager_; // on IO task runner
379 std::shared_ptr<fml::SyncSwitch> is_gpu_disabled_sync_switch_;
380
381 fml::WeakPtr<Engine> weak_engine_; // to be shared across threads
382 fml::TaskRunnerAffineWeakPtr<Rasterizer>
383 weak_rasterizer_; // to be shared across threads
384 fml::WeakPtr<PlatformView>
385 weak_platform_view_; // to be shared across threads
386
387 std::unordered_map<std::string_view, // method
388 std::pair<fml::RefPtr<fml::TaskRunner>,
389 ServiceProtocolHandler> // task-runner/function
390 // pair
391 >
392 service_protocol_handlers_;
393 bool is_setup_ = false;
394 uint64_t next_pointer_flow_id_ = 0;
395
396 bool first_frame_rasterized_ = false;
397 std::atomic<bool> waiting_for_first_frame_ = true;
398 std::mutex waiting_for_first_frame_mutex_;
399 std::condition_variable waiting_for_first_frame_condition_;
400
401 // Written in the UI thread and read from the raster thread. Hence make it
402 // atomic.
403 std::atomic<bool> needs_report_timings_{false};
404
405 // Whether there's a task scheduled to report the timings to Dart through
406 // ui.Window.onReportTimings.
407 bool frame_timings_report_scheduled_ = false;
408
409 // Vector of FrameTiming::kCount * n timestamps for n frames whose timings
410 // have not been reported yet. Vector of ints instead of FrameTiming is stored
411 // here for easier conversions to Dart objects.
412 std::vector<int64_t> unreported_timings_;
413
414 // A cache of `Engine::GetDisplayRefreshRate` (only callable in the UI thread)
415 // so we can access it from `Rasterizer` (in the raster thread).
416 //
417 // The atomic is for extra thread safety as this is written in the UI thread
418 // and read from the raster thread.
419 std::atomic<float> display_refresh_rate_ = 0.0f;
420
421 // How many frames have been timed since last report.
422 size_t UnreportedFramesCount() const;
423
424 Shell(DartVMRef vm, TaskRunners task_runners, Settings settings);
425
426 static std::unique_ptr<Shell> CreateShellOnPlatformThread(
427 DartVMRef vm,
428 TaskRunners task_runners,
429 const PlatformData platform_data,
430 Settings settings,
431 fml::RefPtr<const DartSnapshot> isolate_snapshot,
432 const Shell::CreateCallback<PlatformView>& on_create_platform_view,
433 const Shell::CreateCallback<Rasterizer>& on_create_rasterizer);
434
435 bool Setup(std::unique_ptr<PlatformView> platform_view,
436 std::unique_ptr<Engine> engine,
437 std::unique_ptr<Rasterizer> rasterizer,
438 std::unique_ptr<ShellIOManager> io_manager);
439
440 void ReportTimings();
441
442 // |PlatformView::Delegate|
443 void OnPlatformViewCreated(std::unique_ptr<Surface> surface) override;
444
445 // |PlatformView::Delegate|
446 void OnPlatformViewDestroyed() override;
447
448 // |PlatformView::Delegate|
449 void OnPlatformViewSetViewportMetrics(
450 const ViewportMetrics& metrics) override;
451
452 // |PlatformView::Delegate|
453 void OnPlatformViewDispatchPlatformMessage(
454 fml::RefPtr<PlatformMessage> message) override;
455
456 // |PlatformView::Delegate|
457 void OnPlatformViewDispatchPointerDataPacket(
458 std::unique_ptr<PointerDataPacket> packet) override;
459
460 // |PlatformView::Delegate|
461 void OnPlatformViewDispatchSemanticsAction(
462 int32_t id,
463 SemanticsAction action,
464 std::vector<uint8_t> args) override;
465
466 // |PlatformView::Delegate|
467 void OnPlatformViewSetSemanticsEnabled(bool enabled) override;
468
469 // |shell:PlatformView::Delegate|
470 void OnPlatformViewSetAccessibilityFeatures(int32_t flags) override;
471
472 // |PlatformView::Delegate|
473 void OnPlatformViewRegisterTexture(
474 std::shared_ptr<flutter::Texture> texture) override;
475
476 // |PlatformView::Delegate|
477 void OnPlatformViewUnregisterTexture(int64_t texture_id) override;
478
479 // |PlatformView::Delegate|
480 void OnPlatformViewMarkTextureFrameAvailable(int64_t texture_id) override;
481
482 // |PlatformView::Delegate|
483 void OnPlatformViewSetNextFrameCallback(const fml::closure& closure) override;
484
485 // |PlatformView::Delegate|
486 std::unique_ptr<std::vector<std::string>> ComputePlatformViewResolvedLocale(
487 const std::vector<std::string>& supported_locale_data) override;
488
489 // |Animator::Delegate|
490 void OnAnimatorBeginFrame(fml::TimePoint frame_target_time) override;
491
492 // |Animator::Delegate|
493 void OnAnimatorNotifyIdle(int64_t deadline) override;
494
495 // |Animator::Delegate|
496 void OnAnimatorDraw(fml::RefPtr<Pipeline<flutter::LayerTree>> pipeline,
497 fml::TimePoint frame_target_time) override;
498
499 // |Animator::Delegate|
500 void OnAnimatorDrawLastLayerTree() override;
501
502 // |Engine::Delegate|
503 void OnEngineUpdateSemantics(
504 SemanticsNodeUpdates update,
505 CustomAccessibilityActionUpdates actions) override;
506
507 // |Engine::Delegate|
508 void OnEngineHandlePlatformMessage(
509 fml::RefPtr<PlatformMessage> message) override;
510
511 void HandleEngineSkiaMessage(fml::RefPtr<PlatformMessage> message);
512
513 // |Engine::Delegate|
514 void OnPreEngineRestart() override;
515
516 // |Engine::Delegate|
517 void UpdateIsolateDescription(const std::string isolate_name,
518 int64_t isolate_port) override;
519
520 // |Engine::Delegate|
521 void SetNeedsReportTimings(bool value) override;
522
523 // |Engine::Delegate|
524 std::unique_ptr<std::vector<std::string>> ComputePlatformResolvedLocale(
525 const std::vector<std::string>& supported_locale_data) override;
526
527 // |Rasterizer::Delegate|
528 void OnFrameRasterized(const FrameTiming&) override;
529
530 // |Rasterizer::Delegate|
531 fml::Milliseconds GetFrameBudget() override;
532
533 // |Rasterizer::Delegate|
534 fml::TimePoint GetLatestFrameTargetTime() const override;
535
536 // |ServiceProtocol::Handler|
537 fml::RefPtr<fml::TaskRunner> GetServiceProtocolHandlerTaskRunner(
538 std::string_view method) const override;
539
540 // |ServiceProtocol::Handler|
541 bool HandleServiceProtocolMessage(
542 std::string_view method, // one if the extension names specified above.
543 const ServiceProtocolMap& params,
544 rapidjson::Document* response) override;
545
546 // |ServiceProtocol::Handler|
547 ServiceProtocol::Handler::Description GetServiceProtocolDescription()
548 const override;
549
550 // Service protocol handler
551 bool OnServiceProtocolScreenshot(
552 const ServiceProtocol::Handler::ServiceProtocolMap& params,
553 rapidjson::Document* response);
554
555 // Service protocol handler
556 bool OnServiceProtocolScreenshotSKP(
557 const ServiceProtocol::Handler::ServiceProtocolMap& params,
558 rapidjson::Document* response);
559
560 // Service protocol handler
561 bool OnServiceProtocolRunInView(
562 const ServiceProtocol::Handler::ServiceProtocolMap& params,
563 rapidjson::Document* response);
564
565 // Service protocol handler
566 bool OnServiceProtocolFlushUIThreadTasks(
567 const ServiceProtocol::Handler::ServiceProtocolMap& params,
568 rapidjson::Document* response);
569
570 // Service protocol handler
571 bool OnServiceProtocolSetAssetBundlePath(
572 const ServiceProtocol::Handler::ServiceProtocolMap& params,
573 rapidjson::Document* response);
574
575 // Service protocol handler
576 bool OnServiceProtocolGetDisplayRefreshRate(
577 const ServiceProtocol::Handler::ServiceProtocolMap& params,
578 rapidjson::Document* response);
579
580 // Service protocol handler
581 //
582 // The returned SkSLs are base64 encoded. Decode before storing them to files.
583 bool OnServiceProtocolGetSkSLs(
584 const ServiceProtocol::Handler::ServiceProtocolMap& params,
585 rapidjson::Document* response);
586
587 // Service protocol handler
588 bool OnServiceProtocolEstimateRasterCacheMemory(
589 const ServiceProtocol::Handler::ServiceProtocolMap& params,
590 rapidjson::Document* response);
591
592 fml::WeakPtrFactory<Shell> weak_factory_;
593
594 // For accessing the Shell via the raster thread, necessary for various
595 // rasterizer callbacks.
596 std::unique_ptr<fml::TaskRunnerAffineWeakPtrFactory<Shell>> weak_factory_gpu_;
597
598 friend class testing::ShellTest;
599
600 FML_DISALLOW_COPY_AND_ASSIGN(Shell);
601};
602
603} // namespace flutter
604
605#endif // SHELL_COMMON_SHELL_H_
606