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_RUNTIME_DART_SERVICE_ISOLATE_H_
6#define FLUTTER_RUNTIME_DART_SERVICE_ISOLATE_H_
7
8#include <functional>
9#include <mutex>
10#include <set>
11#include <string>
12
13#include "flutter/fml/compiler_specific.h"
14#include "third_party/dart/runtime/include/dart_api.h"
15
16namespace flutter {
17
18//------------------------------------------------------------------------------
19/// @brief Utility methods for interacting with the DartVM managed service
20/// isolate present in debug and profile runtime modes.
21///
22class DartServiceIsolate {
23 public:
24 //----------------------------------------------------------------------------
25 /// The handle used to refer to callbacks registered with the service isolate.
26 ///
27 using CallbackHandle = ptrdiff_t;
28
29 //----------------------------------------------------------------------------
30 /// A callback made by the Dart VM when the observatory is ready. The argument
31 /// indicates the observatory URI.
32 ///
33 using ObservatoryServerStateCallback =
34 std::function<void(const std::string& observatory_uri)>;
35
36 //----------------------------------------------------------------------------
37 /// @brief Start the service isolate. This call may only be made in the
38 /// Dart VM initiated isolate creation callback. It is only valid
39 /// to make this call when the VM explicitly requests the creation
40 /// of the service isolate. The VM does this by specifying the
41 /// script URI to be `DART_VM_SERVICE_ISOLATE_NAME`. The isolate
42 /// to be designated as the service isolate must already be
43 /// created (but not running) when this call is made.
44 ///
45 /// @param[in] server_ip The service protocol IP address.
46 /// @param[in] server_port The service protocol port.
47 /// @param[in] embedder_tag_handler The library tag handler.
48 /// @param[in] disable_origin_check If websocket origin checks must
49 /// be enabled.
50 /// @param[in] disable_service_auth_codes If service auth codes must be
51 /// enabled.
52 /// @param[in] enable_service_port_fallback If fallback to port 0 must be
53 /// enabled when the bind fails.
54 /// @param error The error when this method
55 /// returns false. This string must
56 /// be freed by the caller using
57 /// `free`.
58 ///
59 /// @return If the startup was successful. Refer to the `error` for
60 /// details on failure.
61 ///
62 static bool Startup(std::string server_ip,
63 intptr_t server_port,
64 Dart_LibraryTagHandler embedder_tag_handler,
65 bool disable_origin_check,
66 bool disable_service_auth_codes,
67 bool enable_service_port_fallback,
68 char** error);
69
70 //----------------------------------------------------------------------------
71 /// @brief Add a callback that will get invoked when the observatory
72 /// starts up. If the observatory has already started before this
73 /// call is made, the callback is invoked immediately.
74 ///
75 /// This method is thread safe.
76 ///
77 /// @param[in] callback The callback with information about the observatory.
78 ///
79 /// @return A handle for the callback that can be used later in
80 /// `RemoveServerStatusCallback`.
81 ///
82 [[nodiscard]] static CallbackHandle AddServerStatusCallback(
83 const ObservatoryServerStateCallback& callback);
84
85 //----------------------------------------------------------------------------
86 /// @brief Removed a callback previously registered via
87 /// `AddServiceStatusCallback`.
88 ///
89 /// This method is thread safe.
90 ///
91 /// @param[in] handle The handle
92 ///
93 /// @return If the callback was unregistered. This may fail if there was
94 /// no such callback with that handle.
95 ///
96 static bool RemoveServerStatusCallback(CallbackHandle handle);
97
98 private:
99 // Native entries.
100 static void NotifyServerState(Dart_NativeArguments args);
101 static void Shutdown(Dart_NativeArguments args);
102
103 static std::mutex callbacks_mutex_;
104 static std::set<std::unique_ptr<ObservatoryServerStateCallback>> callbacks_;
105};
106
107} // namespace flutter
108
109#endif // FLUTTER_RUNTIME_DART_SERVICE_ISOLATE_H_
110