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 | |
16 | namespace flutter { |
17 | |
18 | //------------------------------------------------------------------------------ |
19 | /// @brief Utility methods for interacting with the DartVM managed service |
20 | /// isolate present in debug and profile runtime modes. |
21 | /// |
22 | class 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 | |