Flutter Engine
flutter::PlatformConfiguration Class Referencefinal

A class for holding and distributing platform-level information to and from the Dart code in Flutter's framework. More...

#include <platform_configuration.h>

Public Member Functions

 PlatformConfiguration (PlatformConfigurationClient *client)
 Creates a new PlatformConfiguration, typically created by the RuntimeController. More...
 
 PlatformConfiguration (const PlatformConfiguration &)=delete
 
PlatformConfigurationoperator= (const PlatformConfiguration &)=delete
 
 ~PlatformConfiguration ()
 
PlatformConfigurationClientclient () const
 Access to the platform configuration client (which typically is implemented by the RuntimeController). More...
 
void DidCreateIsolate ()
 Called by the RuntimeController once it has created the root isolate, so that the PlatformController can get a handle to the 'dart:ui' library. More...
 
void UpdateLocales (const std::vector< std::string > &locales)
 Update the specified locale data in the framework. More...
 
void UpdateUserSettingsData (const std::string &data)
 Update the user settings data in the framework. More...
 
void UpdateLifecycleState (const std::string &data)
 Updates the lifecycle state data in the framework. More...
 
void UpdateSemanticsEnabled (bool enabled)
 Notifies the PlatformConfiguration that the embedder has expressed an opinion about whether the accessibility tree should be generated or not. This call originates in the platform view and is forwarded to the PlatformConfiguration here by the engine. More...
 
void UpdateAccessibilityFeatures (int32_t flags)
 Forward the preference of accessibility features that must be enabled in the semantics tree to the framwork. More...
 
void DispatchPlatformMessage (fml::RefPtr< PlatformMessage > message)
 Notifies the PlatformConfiguration that the client has sent it a message. This call originates in the platform view and has been forwarded through the engine to here. More...
 
void DispatchSemanticsAction (int32_t id, SemanticsAction action, std::vector< uint8_t > args)
 Notifies the framework that the embedder encountered an accessibility related action on the specified node. This call originates on the platform view and has been forwarded to the platform configuration here by the engine. More...
 
void BeginFrame (fml::TimePoint frame_time)
 Notifies the framework that it is time to begin working on a new frame previously scheduled via a call to PlatformConfigurationClient::ScheduleFrame. This call originates in the animator. More...
 
void ReportTimings (std::vector< int64_t > timings)
 Dart code cannot fully measure the time it takes for a specific frame to be rendered. This is because Dart code only runs on the UI task runner. That is only a small part of the overall frame workload. The GPU task runner frame workload is executed on a thread where Dart code cannot run (and hence instrument). Besides, due to the pipelined nature of rendering in Flutter, there may be multiple frame workloads being processed at any given time. However, for non-Timeline based profiling, it is useful for trace collection and processing to happen in Dart. To do this, the GPU task runner frame workloads need to be instrumented separately. After a set number of these profiles have been gathered, they need to be reported back to Dart code. The engine reports this extra instrumentation information back to the framework by invoking this method at predefined intervals. More...
 
Windowget_window (int window_id)
 Retrieves the Window with the given ID managed by the PlatformConfiguration. More...
 
void CompletePlatformMessageResponse (int response_id, std::vector< uint8_t > data)
 Responds to a previous platform message to the engine from the framework. More...
 
void CompletePlatformMessageEmptyResponse (int response_id)
 Responds to a previous platform message to the engine from the framework with an empty response. More...
 

Static Public Member Functions

static void RegisterNatives (tonic::DartLibraryNatives *natives)
 Registers the native handlers for Dart functions that this class handles. More...
 

Detailed Description

A class for holding and distributing platform-level information to and from the Dart code in Flutter's framework.

It handles communication between the engine and the framework, and owns the main window.

It communicates with the RuntimeController through the use of a PlatformConfigurationClient interface, which the RuntimeController defines.

Definition at line 192 of file platform_configuration.h.

Constructor & Destructor Documentation

◆ PlatformConfiguration() [1/2]

flutter::PlatformConfiguration::PlatformConfiguration ( PlatformConfigurationClient client)
explicit

Creates a new PlatformConfiguration, typically created by the RuntimeController.

Parameters
[in]clientThe PlatformConfigurationClient to be injected into the PlatformConfiguration. This client is used to forward requests to the RuntimeController.

Definition at line 192 of file platform_configuration.cc.

194  : client_(client) {}
PlatformConfigurationClient * client() const
Access to the platform configuration client (which typically is implemented by the RuntimeController)...

◆ PlatformConfiguration() [2/2]

flutter::PlatformConfiguration::PlatformConfiguration ( const PlatformConfiguration )
delete

◆ ~PlatformConfiguration()

flutter::PlatformConfiguration::~PlatformConfiguration ( )

Definition at line 196 of file platform_configuration.cc.

196 {}

Member Function Documentation

◆ BeginFrame()

void flutter::PlatformConfiguration::BeginFrame ( fml::TimePoint  frame_time)

Notifies the framework that it is time to begin working on a new frame previously scheduled via a call to PlatformConfigurationClient::ScheduleFrame. This call originates in the animator.

The frame time given as the argument indicates the point at which the current frame interval began. It is very slightly (because of scheduling overhead) in the past. If a new layer tree is not produced and given to the GPU task runner within one frame interval from this point, the Flutter application will jank.

This method calls the ::_beginFrame method in hooks.dart.

Parameters
[in]frame_timeThe point at which the current frame interval began. May be used by animation interpolators, physics simulations, etc..

Definition at line 322 of file platform_configuration.cc.

References flutter::UIDartState::Current(), tonic::DartPersistentValue::dart_state(), tonic::DartInvokeField(), flutter::UIDartState::FlushMicrotasksNow(), tonic::LogIfError(), and tonic::DartPersistentValue::value().

322  {
323  std::shared_ptr<tonic::DartState> dart_state = library_.dart_state().lock();
324  if (!dart_state) {
325  return;
326  }
327  tonic::DartState::Scope scope(dart_state);
328 
329  int64_t microseconds = (frameTime - fml::TimePoint()).ToMicroseconds();
330 
331  tonic::LogIfError(tonic::DartInvokeField(library_.value(), "_beginFrame",
332  {
333  Dart_NewInteger(microseconds),
334  }));
335 
337 
338  tonic::LogIfError(tonic::DartInvokeField(library_.value(), "_drawFrame", {}));
339 }
Dart_PersistentHandle value() const
Dart_Handle DartInvokeField(Dart_Handle target, const char *name, std::initializer_list< Dart_Handle > args)
Definition: dart_invoke.cc:12
const std::weak_ptr< DartState > & dart_state() const
bool LogIfError(Dart_Handle handle)
Definition: dart_error.cc:15
static UIDartState * Current()

◆ client()

PlatformConfigurationClient* flutter::PlatformConfiguration::client ( ) const
inline

Access to the platform configuration client (which typically is implemented by the RuntimeController).

Returns
Returns the client used to construct this PlatformConfiguration.

Definition at line 217 of file platform_configuration.h.

References action, args, flutter::DispatchPlatformMessage(), flutter::DispatchSemanticsAction(), and flutter::flags.

Referenced by flutter::ComputePlatformResolvedLocale(), and flutter::decodeStrut().

217 { return client_; }

◆ CompletePlatformMessageEmptyResponse()

void flutter::PlatformConfiguration::CompletePlatformMessageEmptyResponse ( int  response_id)

Responds to a previous platform message to the engine from the framework with an empty response.

Parameters
[in]response_idThe unique id that identifies the original platform message to respond to.

Definition at line 367 of file platform_configuration.cc.

368  {
369  if (!response_id) {
370  return;
371  }
372  auto it = pending_responses_.find(response_id);
373  if (it == pending_responses_.end()) {
374  return;
375  }
376  auto response = std::move(it->second);
377  pending_responses_.erase(it);
378  response->CompleteEmpty();
379 }

◆ CompletePlatformMessageResponse()

void flutter::PlatformConfiguration::CompletePlatformMessageResponse ( int  response_id,
std::vector< uint8_t >  data 
)

Responds to a previous platform message to the engine from the framework.

Parameters
[in]response_idThe unique id that identifies the original platform message to respond to.
[in]dataThe data to send back in the response.

Definition at line 381 of file platform_configuration.cc.

383  {
384  if (!response_id) {
385  return;
386  }
387  auto it = pending_responses_.find(response_id);
388  if (it == pending_responses_.end()) {
389  return;
390  }
391  auto response = std::move(it->second);
392  pending_responses_.erase(it);
393  response->Complete(std::make_unique<fml::DataMapping>(std::move(data)));
394 }

◆ DidCreateIsolate()

void flutter::PlatformConfiguration::DidCreateIsolate ( )

Called by the RuntimeController once it has created the root isolate, so that the PlatformController can get a handle to the 'dart:ui' library.

It uses the handle to call the hooks in hooks.dart.

Definition at line 198 of file platform_configuration.cc.

References tonic::DartState::Current(), tonic::DartPersistentValue::Set(), and tonic::ToDart().

198  {
199  library_.Set(tonic::DartState::Current(),
200  Dart_LookupLibrary(tonic::ToDart("dart:ui")));
201  windows_.insert(std::make_pair(0, std::unique_ptr<Window>(new Window{
202  0, ViewportMetrics{1.0, 0.0, 0.0}})));
203 }
void Set(DartState *dart_state, Dart_Handle value)
static DartState * Current()
Definition: dart_state.cc:55
Dart_Handle ToDart(const T &object)

◆ DispatchPlatformMessage()

void flutter::PlatformConfiguration::DispatchPlatformMessage ( fml::RefPtr< PlatformMessage message)

Notifies the PlatformConfiguration that the client has sent it a message. This call originates in the platform view and has been forwarded through the engine to here.

Parameters
[in]messageThe message sent from the embedder to the Dart application.

Definition at line 270 of file platform_configuration.cc.

References tonic::DartPersistentValue::dart_state(), tonic::DartInvokeField(), FML_DLOG, tonic::LogIfError(), tonic::ToDart(), and tonic::DartPersistentValue::value().

271  {
272  std::shared_ptr<tonic::DartState> dart_state = library_.dart_state().lock();
273  if (!dart_state) {
274  FML_DLOG(WARNING)
275  << "Dropping platform message for lack of DartState on channel: "
276  << message->channel();
277  return;
278  }
279  tonic::DartState::Scope scope(dart_state);
280  Dart_Handle data_handle =
281  (message->hasData()) ? ToByteData(message->data()) : Dart_Null();
282  if (Dart_IsError(data_handle)) {
283  FML_DLOG(WARNING)
284  << "Dropping platform message because of a Dart error on channel: "
285  << message->channel();
286  return;
287  }
288 
289  int response_id = 0;
290  if (auto response = message->response()) {
291  response_id = next_response_id_++;
292  pending_responses_[response_id] = response;
293  }
294 
296  tonic::DartInvokeField(library_.value(), "_dispatchPlatformMessage",
297  {tonic::ToDart(message->channel()), data_handle,
298  tonic::ToDart(response_id)}));
299 }
Dart_PersistentHandle value() const
Dart_Handle DartInvokeField(Dart_Handle target, const char *name, std::initializer_list< Dart_Handle > args)
Definition: dart_invoke.cc:12
const std::weak_ptr< DartState > & dart_state() const
#define FML_DLOG(severity)
Definition: logging.h:85
Dart_Handle ToDart(const T &object)
bool LogIfError(Dart_Handle handle)
Definition: dart_error.cc:15

◆ DispatchSemanticsAction()

void flutter::PlatformConfiguration::DispatchSemanticsAction ( int32_t  id,
SemanticsAction  action,
std::vector< uint8_t >  args 
)

Notifies the framework that the embedder encountered an accessibility related action on the specified node. This call originates on the platform view and has been forwarded to the platform configuration here by the engine.

Parameters
[in]idThe identifier of the accessibility node.
[in]actionThe accessibility related action performed on the node of the specified ID.
[in]argsOptional data that applies to the specified action.

Definition at line 301 of file platform_configuration.cc.

References tonic::DartPersistentValue::dart_state(), tonic::DartInvokeField(), tonic::LogIfError(), tonic::ToDart(), and tonic::DartPersistentValue::value().

303  {
304  std::shared_ptr<tonic::DartState> dart_state = library_.dart_state().lock();
305  if (!dart_state) {
306  return;
307  }
308  tonic::DartState::Scope scope(dart_state);
309 
310  Dart_Handle args_handle = (args.empty()) ? Dart_Null() : ToByteData(args);
311 
312  if (Dart_IsError(args_handle)) {
313  return;
314  }
315 
317  library_.value(), "_dispatchSemanticsAction",
318  {tonic::ToDart(id), tonic::ToDart(static_cast<int32_t>(action)),
319  args_handle}));
320 }
G_BEGIN_DECLS FlValue * args
Dart_PersistentHandle value() const
Dart_Handle DartInvokeField(Dart_Handle target, const char *name, std::initializer_list< Dart_Handle > args)
Definition: dart_invoke.cc:12
SemanticsAction action
const std::weak_ptr< DartState > & dart_state() const
Dart_Handle ToDart(const T &object)
bool LogIfError(Dart_Handle handle)
Definition: dart_error.cc:15

◆ get_window()

Window* flutter::PlatformConfiguration::get_window ( int  window_id)
inline

Retrieves the Window with the given ID managed by the PlatformConfiguration.

Parameters
[in]window_idThe id of the window to find and return.
Returns
a pointer to the Window.

Definition at line 372 of file platform_configuration.h.

Referenced by flutter::Scene::create(), flutter::Canvas::drawShadow(), and flutter::testing::TEST_F().

372 { return windows_[window_id].get(); }

◆ operator=()

PlatformConfiguration& flutter::PlatformConfiguration::operator= ( const PlatformConfiguration )
delete

◆ RegisterNatives()

void flutter::PlatformConfiguration::RegisterNatives ( tonic::DartLibraryNatives natives)
static

Registers the native handlers for Dart functions that this class handles.

Parameters
[in]nativesThe natives registry that the functions will be registered with.

Definition at line 417 of file platform_configuration.cc.

References flutter::_ComputePlatformResolvedLocale(), and tonic::DartLibraryNatives::Register().

Referenced by flutter::DartUI::InitForGlobal().

418  {
419  natives->Register({
420  {"PlatformConfiguration_defaultRouteName", DefaultRouteName, 1, true},
421  {"PlatformConfiguration_scheduleFrame", ScheduleFrame, 1, true},
422  {"PlatformConfiguration_sendPlatformMessage", _SendPlatformMessage, 4,
423  true},
424  {"PlatformConfiguration_respondToPlatformMessage",
425  _RespondToPlatformMessage, 3, true},
426  {"PlatformConfiguration_render", Render, 3, true},
427  {"PlatformConfiguration_updateSemantics", UpdateSemantics, 2, true},
428  {"PlatformConfiguration_setIsolateDebugName", SetIsolateDebugName, 2,
429  true},
430  {"PlatformConfiguration_reportUnhandledException",
431  ReportUnhandledException, 2, true},
432  {"PlatformConfiguration_setNeedsReportTimings", SetNeedsReportTimings, 2,
433  true},
434  {"PlatformConfiguration_getPersistentIsolateData",
435  GetPersistentIsolateData, 1, true},
436  {"PlatformConfiguration_computePlatformResolvedLocale",
438  });
439 }
static void _ComputePlatformResolvedLocale(Dart_NativeArguments args)
void Register(std::initializer_list< Entry > entries)

◆ ReportTimings()

void flutter::PlatformConfiguration::ReportTimings ( std::vector< int64_t >  timings)

Dart code cannot fully measure the time it takes for a specific frame to be rendered. This is because Dart code only runs on the UI task runner. That is only a small part of the overall frame workload. The GPU task runner frame workload is executed on a thread where Dart code cannot run (and hence instrument). Besides, due to the pipelined nature of rendering in Flutter, there may be multiple frame workloads being processed at any given time. However, for non-Timeline based profiling, it is useful for trace collection and processing to happen in Dart. To do this, the GPU task runner frame workloads need to be instrumented separately. After a set number of these profiles have been gathered, they need to be reported back to Dart code. The engine reports this extra instrumentation information back to the framework by invoking this method at predefined intervals.

See also
FrameTiming
Parameters
[in]timingsCollection of FrameTiming::kCount * n timestamps for n frames whose timings have not been reported yet. A collection of integers is reported here for easier conversions to Dart objects. The timestamps are measured against the system monotonic clock measured in microseconds.

Definition at line 341 of file platform_configuration.cc.

References tonic::DartPersistentValue::dart_state(), tonic::DartInvokeField(), FML_CHECK, FML_DCHECK, tonic::LogIfError(), and tonic::DartPersistentValue::value().

341  {
342  std::shared_ptr<tonic::DartState> dart_state = library_.dart_state().lock();
343  if (!dart_state) {
344  return;
345  }
346  tonic::DartState::Scope scope(dart_state);
347 
348  Dart_Handle data_handle =
349  Dart_NewTypedData(Dart_TypedData_kInt64, timings.size());
350 
351  Dart_TypedData_Type type;
352  void* data = nullptr;
353  intptr_t num_acquired = 0;
354  FML_CHECK(!Dart_IsError(
355  Dart_TypedDataAcquireData(data_handle, &type, &data, &num_acquired)));
356  FML_DCHECK(num_acquired == static_cast<int>(timings.size()));
357 
358  memcpy(data, timings.data(), sizeof(int64_t) * timings.size());
359  FML_CHECK(Dart_TypedDataReleaseData(data_handle));
360 
361  tonic::LogIfError(tonic::DartInvokeField(library_.value(), "_reportTimings",
362  {
363  data_handle,
364  }));
365 }
#define FML_DCHECK(condition)
Definition: logging.h:86
Dart_PersistentHandle value() const
Dart_Handle DartInvokeField(Dart_Handle target, const char *name, std::initializer_list< Dart_Handle > args)
Definition: dart_invoke.cc:12
const std::weak_ptr< DartState > & dart_state() const
#define FML_CHECK(condition)
Definition: logging.h:68
bool LogIfError(Dart_Handle handle)
Definition: dart_error.cc:15

◆ UpdateAccessibilityFeatures()

void flutter::PlatformConfiguration::UpdateAccessibilityFeatures ( int32_t  flags)

Forward the preference of accessibility features that must be enabled in the semantics tree to the framwork.

Parameters
[in]flagsThe accessibility features that must be generated in the semantics tree.

Definition at line 258 of file platform_configuration.cc.

References tonic::DartPersistentValue::dart_state(), tonic::DartInvokeField(), tonic::LogIfError(), tonic::ToDart(), and tonic::DartPersistentValue::value().

258  {
259  std::shared_ptr<tonic::DartState> dart_state = library_.dart_state().lock();
260  if (!dart_state) {
261  return;
262  }
263  tonic::DartState::Scope scope(dart_state);
264 
266  "_updateAccessibilityFeatures",
267  {tonic::ToDart(values)}));
268 }
Dart_PersistentHandle value() const
Dart_Handle DartInvokeField(Dart_Handle target, const char *name, std::initializer_list< Dart_Handle > args)
Definition: dart_invoke.cc:12
const std::weak_ptr< DartState > & dart_state() const
Dart_Handle ToDart(const T &object)
bool LogIfError(Dart_Handle handle)
Definition: dart_error.cc:15

◆ UpdateLifecycleState()

void flutter::PlatformConfiguration::UpdateLifecycleState ( const std::string &  data)

Updates the lifecycle state data in the framework.

Parameters
[in]dataThe lifecycle state data.

Definition at line 233 of file platform_configuration.cc.

References tonic::DartPersistentValue::dart_state(), tonic::DartInvokeField(), tonic::LogIfError(), tonic::StdStringToDart(), and tonic::DartPersistentValue::value().

233  {
234  std::shared_ptr<tonic::DartState> dart_state = library_.dart_state().lock();
235  if (!dart_state) {
236  return;
237  }
238  tonic::DartState::Scope scope(dart_state);
240  "_updateLifecycleState",
241  {
243  }));
244 }
Dart_PersistentHandle value() const
Dart_Handle DartInvokeField(Dart_Handle target, const char *name, std::initializer_list< Dart_Handle > args)
Definition: dart_invoke.cc:12
const std::weak_ptr< DartState > & dart_state() const
bool LogIfError(Dart_Handle handle)
Definition: dart_error.cc:15
Dart_Handle StdStringToDart(const std::string &val)

◆ UpdateLocales()

void flutter::PlatformConfiguration::UpdateLocales ( const std::vector< std::string > &  locales)

Update the specified locale data in the framework.

Parameters
[in]locale_dataThe locale data. This should consist of groups of 4 strings, each group representing a single locale.

Definition at line 205 of file platform_configuration.cc.

References tonic::DartPersistentValue::dart_state(), tonic::DartInvokeField(), tonic::LogIfError(), and tonic::DartPersistentValue::value().

206  {
207  std::shared_ptr<tonic::DartState> dart_state = library_.dart_state().lock();
208  if (!dart_state) {
209  return;
210  }
211  tonic::DartState::Scope scope(dart_state);
213  library_.value(), "_updateLocales",
214  {
215  tonic::ToDart<std::vector<std::string>>(locales),
216  }));
217 }
Dart_PersistentHandle value() const
Dart_Handle DartInvokeField(Dart_Handle target, const char *name, std::initializer_list< Dart_Handle > args)
Definition: dart_invoke.cc:12
const std::weak_ptr< DartState > & dart_state() const
bool LogIfError(Dart_Handle handle)
Definition: dart_error.cc:15

◆ UpdateSemanticsEnabled()

void flutter::PlatformConfiguration::UpdateSemanticsEnabled ( bool  enabled)

Notifies the PlatformConfiguration that the embedder has expressed an opinion about whether the accessibility tree should be generated or not. This call originates in the platform view and is forwarded to the PlatformConfiguration here by the engine.

Parameters
[in]enabledWhether the accessibility tree is enabled or disabled.

Definition at line 246 of file platform_configuration.cc.

References tonic::DartPersistentValue::dart_state(), tonic::DartInvokeField(), tonic::LogIfError(), flutter::UIDartState::ThrowIfUIOperationsProhibited(), tonic::ToDart(), and tonic::DartPersistentValue::value().

246  {
247  std::shared_ptr<tonic::DartState> dart_state = library_.dart_state().lock();
248  if (!dart_state) {
249  return;
250  }
251  tonic::DartState::Scope scope(dart_state);
253 
255  library_.value(), "_updateSemanticsEnabled", {tonic::ToDart(enabled)}));
256 }
Dart_PersistentHandle value() const
Dart_Handle DartInvokeField(Dart_Handle target, const char *name, std::initializer_list< Dart_Handle > args)
Definition: dart_invoke.cc:12
const std::weak_ptr< DartState > & dart_state() const
static void ThrowIfUIOperationsProhibited()
Dart_Handle ToDart(const T &object)
bool LogIfError(Dart_Handle handle)
Definition: dart_error.cc:15

◆ UpdateUserSettingsData()

void flutter::PlatformConfiguration::UpdateUserSettingsData ( const std::string &  data)

Update the user settings data in the framework.

Parameters
[in]dataThe user settings data.

Definition at line 219 of file platform_configuration.cc.

References tonic::DartPersistentValue::dart_state(), tonic::DartInvokeField(), tonic::LogIfError(), tonic::StdStringToDart(), and tonic::DartPersistentValue::value().

219  {
220  std::shared_ptr<tonic::DartState> dart_state = library_.dart_state().lock();
221  if (!dart_state) {
222  return;
223  }
224  tonic::DartState::Scope scope(dart_state);
225 
227  "_updateUserSettingsData",
228  {
230  }));
231 }
Dart_PersistentHandle value() const
Dart_Handle DartInvokeField(Dart_Handle target, const char *name, std::initializer_list< Dart_Handle > args)
Definition: dart_invoke.cc:12
const std::weak_ptr< DartState > & dart_state() const
bool LogIfError(Dart_Handle handle)
Definition: dart_error.cc:15
Dart_Handle StdStringToDart(const std::string &val)

The documentation for this class was generated from the following files: