runtime/dart_vm.h

// Copyright 2013 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef FLUTTER_RUNTIME_DART_VM_H_
#define FLUTTER_RUNTIME_DART_VM_H_

#include <memory>
#include <string>

#include "flutter/common/settings.h"
#include "flutter/fml/build_config.h"
#include "flutter/fml/closure.h"
#include "flutter/fml/macros.h"
#include "flutter/fml/memory/ref_counted.h"
#include "flutter/fml/memory/ref_ptr.h"
#include "flutter/fml/memory/weak_ptr.h"
#include "flutter/fml/message_loop.h"
#include "flutter/lib/ui/isolate_name_server/isolate_name_server.h"
#include "flutter/runtime/dart_isolate.h"
#include "flutter/runtime/dart_snapshot.h"
#include "flutter/runtime/dart_vm_data.h"
#include "flutter/runtime/service_protocol.h"
#include "flutter/runtime/skia_concurrent_executor.h"
#include "third_party/dart/runtime/include/dart_api.h"

namespace flutter {

//------------------------------------------------------------------------------
/// @brief      Describes a running instance of the Dart VM. There may only be
///             one running instance of the Dart VM in the process at any given
///             time. The Dart VM may be created and destroyed on any thread.
///             Typically, the first Flutter shell instance running in the
///             process bootstraps the Dart VM in the process as it starts up.
///             This cost is borne on the platform task runner of that first
///             Flutter shell. When the last Flutter shell instance is
///             destroyed, the VM is destroyed as well if all shell instances
///             were launched with the `Settings::leak_vm` flag set to false. If
///             there is any shell launch in the process with `leak_vm` set to
///             true, the VM is never shut down in the process. When the VM is
///             shutdown, the cost of the shutdown is borne on the platform task
///             runner of the last shell instance to be shut down.
///
///             Due to threading considerations, callers may never create an
///             instance of the DartVM directly. All constructors to the DartVM
///             are private. Instead, all callers that need a running VM
///             reference need to access it via the `DartVMRef::Create` call.
///             This call returns a strong reference to the running VM if one
///             exists in the process already. If a running VM instance is not
///             available in the process, a new instance is created and a strong
///             reference returned to the callers. The DartVMRef::Create call
///             ensures that there are no data races during the creation or
///             shutdown of a Dart VM (since a VM may be created and destroyed
///             on any thread). Due to this behavior, all callers needing a
///             running VM instance must provide snapshots and VM settings
///             necessary to create a VM (even if they end up not being used).
///
///             In a running VM instance, the service isolate is launched by
///             default if the VM is configured to do so. All root isolates must
///             be launched and referenced explicitly.
class DartVM {
 public:
  ~DartVM();

  //----------------------------------------------------------------------------
  /// @brief      Checks if VM instances in the process can run precompiled
  ///             code. This call can be made at any time and does not depend on
  ///             a running VM instance. There are no threading restrictions.
  ///
  /// @return     If VM instances in the process run precompiled code.
  ///
  static bool IsRunningPrecompiledCode();

  //----------------------------------------------------------------------------
  /// @brief      The number of times the VM has been launched in the process.
  ///             This call is inherently racy because the VM could be in the
  ///             process of starting up on another thread between the time the
  ///             caller makes this call and uses to result. For this purpose,
  ///             this call is only meant to be used as a debugging aid and
  ///             primarily only used in tests where the threading model is
  ///             consistent.
  ///
  /// @return     The number of times the VM has been launched.
  ///
  static size_t GetVMLaunchCount();

  //----------------------------------------------------------------------------
  /// @brief      The settings used to launch the running VM instance.
  ///
  /// @attention  Even though all callers that need to acquire a strong
  ///             reference to a VM need to provide a valid settings object, the
  ///             VM will only reference the settings used by the first caller
  ///             that bootstraps the VM in the process.
  ///
  /// @return     A valid setting object.
  ///
  const Settings& GetSettings() const;

  //----------------------------------------------------------------------------
  /// @brief      The VM and isolate snapshots used by this running Dart VM
  ///             instance.
  ///
  /// @return     A valid VM data instance.
  ///
  std::shared_ptr<const DartVMData> GetVMData() const;

  //----------------------------------------------------------------------------
  /// @brief      The service protocol instance associated with this running
  ///             Dart VM instance. This object manages native handlers for
  ///             engine vended service protocol methods.
  ///
  /// @return     The service protocol for this Dart VM instance.
  ///
  std::shared_ptr<ServiceProtocol> GetServiceProtocol() const;

  //----------------------------------------------------------------------------
  /// @brief      The isolate name server for this running VM instance. The
  ///             isolate name server maps names (strings) to Dart ports.
  ///             Running isolates can discover and communicate with each other
  ///             by advertising and resolving ports at well known names.
  ///
  /// @return     The isolate name server.
  ///
  std::shared_ptr<IsolateNameServer> GetIsolateNameServer() const;

  //----------------------------------------------------------------------------
  /// @brief      The task runner whose tasks may be executed concurrently on a
  ///             pool of worker threads. All subsystems within a running shell
  ///             instance use this worker pool for their concurrent tasks. This
  ///             also means that the concurrent worker pool may service tasks
  ///             from multiple shell instances. The number of workers in a
  ///             concurrent worker pool depends on the hardware concurrency
  ///             of the target device (usually equal to the number of logical
  ///             CPU cores).
  ///
  ///
  /// @attention  Even though concurrent task queue is associated with a running
  ///             Dart VM instance, the worker pool used by the Flutter engine
  ///             is NOT shared with the Dart VM internal worker pool. The
  ///             presence of this worker pool as member of the Dart VM is
  ///             merely to utilize the strong thread safety guarantees around
  ///             Dart VM lifecycle for the lifecycle of the concurrent worker
  ///             pool as well.
  ///
  /// @return     The task runner for the concurrent worker thread pool.
  ///
  std::shared_ptr<fml::ConcurrentTaskRunner> GetConcurrentWorkerTaskRunner()
      const;

  //----------------------------------------------------------------------------
  /// @brief      The concurrent message loop hosts threads that are used by the
  ///             engine to perform tasks long running background tasks.
  ///             Typically, to post tasks to this message loop, the
  ///             `GetConcurrentWorkerTaskRunner` method may be used.
  ///
  /// @see        GetConcurrentWorkerTaskRunner
  ///
  /// @return     The concurrent message loop used by this running Dart VM
  ///             instance.
  ///
  std::shared_ptr<fml::ConcurrentMessageLoop> GetConcurrentMessageLoop();

 private:
  const Settings settings_;
  std::shared_ptr<fml::ConcurrentMessageLoop> concurrent_message_loop_;
  SkiaConcurrentExecutor skia_concurrent_executor_;
  std::shared_ptr<const DartVMData> vm_data_;
  const std::shared_ptr<IsolateNameServer> isolate_name_server_;
  const std::shared_ptr<ServiceProtocol> service_protocol_;

  friend class DartVMRef;
  friend class DartIsolate;

  static std::shared_ptr<DartVM> Create(
      Settings settings,
      fml::RefPtr<const DartSnapshot> vm_snapshot,
      fml::RefPtr<const DartSnapshot> isolate_snapshot,
      std::shared_ptr<IsolateNameServer> isolate_name_server);

  DartVM(std::shared_ptr<const DartVMData> data,
         std::shared_ptr<IsolateNameServer> isolate_name_server);

  FML_DISALLOW_COPY_AND_ASSIGN(DartVM);
};

}  // namespace flutter

#endif  // FLUTTER_RUNTIME_DART_VM_H_