OLD | NEW |
1 // Copyright 2014 The Chromium Authors. All rights reserved. | 1 // Copyright 2014 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef MOJO_EDK_EMBEDDER_EMBEDDER_H_ | 5 #ifndef MOJO_EDK_EMBEDDER_EMBEDDER_H_ |
6 #define MOJO_EDK_EMBEDDER_EMBEDDER_H_ | 6 #define MOJO_EDK_EMBEDDER_EMBEDDER_H_ |
7 | 7 |
8 #include <memory> | 8 #include <memory> |
9 #include <string> | 9 #include <string> |
10 | 10 |
11 #include "base/callback.h" | 11 #include "base/callback.h" |
12 #include "base/memory/ref_counted.h" | 12 #include "base/memory/ref_counted.h" |
13 #include "base/task_runner.h" | 13 #include "base/task_runner.h" |
14 #include "mojo/edk/embedder/channel_info_forward.h" | 14 #include "mojo/edk/embedder/channel_info_forward.h" |
15 #include "mojo/edk/embedder/process_type.h" | 15 #include "mojo/edk/embedder/process_type.h" |
16 #include "mojo/edk/embedder/scoped_platform_handle.h" | 16 #include "mojo/edk/embedder/scoped_platform_handle.h" |
17 #include "mojo/edk/embedder/slave_info.h" | 17 #include "mojo/edk/embedder/slave_info.h" |
18 #include "mojo/edk/system/system_impl_export.h" | |
19 #include "mojo/public/cpp/system/message_pipe.h" | 18 #include "mojo/public/cpp/system/message_pipe.h" |
20 | 19 |
21 namespace mojo { | 20 namespace mojo { |
22 namespace embedder { | 21 namespace embedder { |
23 | 22 |
24 struct Configuration; | 23 struct Configuration; |
25 class PlatformSupport; | 24 class PlatformSupport; |
26 class ProcessDelegate; | 25 class ProcessDelegate; |
27 | 26 |
28 // Basic configuration/initialization ------------------------------------------ | 27 // Basic configuration/initialization ------------------------------------------ |
29 | 28 |
30 // |Init()| sets up the basic Mojo system environment, making the |Mojo...()| | 29 // |Init()| sets up the basic Mojo system environment, making the |Mojo...()| |
31 // functions available and functional. This is never shut down (except in tests | 30 // functions available and functional. This is never shut down (except in tests |
32 // -- see test_embedder.h). | 31 // -- see test_embedder.h). |
33 | 32 |
34 // Returns the global configuration. In general, you should not need to change | 33 // Returns the global configuration. In general, you should not need to change |
35 // the configuration, but if you do you must do it before calling |Init()|. | 34 // the configuration, but if you do you must do it before calling |Init()|. |
36 MOJO_SYSTEM_IMPL_EXPORT Configuration* GetConfiguration(); | 35 Configuration* GetConfiguration(); |
37 | 36 |
38 // Must be called first, or just after setting configuration parameters, to | 37 // Must be called first, or just after setting configuration parameters, to |
39 // initialize the (global, singleton) system. | 38 // initialize the (global, singleton) system. |
40 MOJO_SYSTEM_IMPL_EXPORT void Init( | 39 void Init(std::unique_ptr<PlatformSupport> platform_support); |
41 std::unique_ptr<PlatformSupport> platform_support); | |
42 | 40 |
43 // Basic functions ------------------------------------------------------------- | 41 // Basic functions ------------------------------------------------------------- |
44 | 42 |
45 // The functions in this section are available once |Init()| has been called. | 43 // The functions in this section are available once |Init()| has been called. |
46 | 44 |
47 // Start waiting on the handle asynchronously. On success, |callback| will be | 45 // Start waiting on the handle asynchronously. On success, |callback| will be |
48 // called exactly once, when |handle| satisfies a signal in |signals| or it | 46 // called exactly once, when |handle| satisfies a signal in |signals| or it |
49 // becomes known that it will never do so. |callback| will be executed on an | 47 // becomes known that it will never do so. |callback| will be executed on an |
50 // arbitrary thread, so it must not call any Mojo system or embedder functions. | 48 // arbitrary thread, so it must not call any Mojo system or embedder functions. |
51 MOJO_SYSTEM_IMPL_EXPORT MojoResult | 49 MojoResult AsyncWait(MojoHandle handle, |
52 AsyncWait(MojoHandle handle, | 50 MojoHandleSignals signals, |
53 MojoHandleSignals signals, | 51 const base::Callback<void(MojoResult)>& callback); |
54 const base::Callback<void(MojoResult)>& callback); | |
55 | 52 |
56 // Creates a |MojoHandle| that wraps the given |PlatformHandle| (taking | 53 // Creates a |MojoHandle| that wraps the given |PlatformHandle| (taking |
57 // ownership of it). This |MojoHandle| can then, e.g., be passed through message | 54 // ownership of it). This |MojoHandle| can then, e.g., be passed through message |
58 // pipes. Note: This takes ownership (and thus closes) |platform_handle| even on | 55 // pipes. Note: This takes ownership (and thus closes) |platform_handle| even on |
59 // failure, which is different from what you'd expect from a Mojo API, but it | 56 // failure, which is different from what you'd expect from a Mojo API, but it |
60 // makes for a more convenient embedder API. | 57 // makes for a more convenient embedder API. |
61 MOJO_SYSTEM_IMPL_EXPORT MojoResult | 58 MojoResult CreatePlatformHandleWrapper( |
62 CreatePlatformHandleWrapper(ScopedPlatformHandle platform_handle, | 59 ScopedPlatformHandle platform_handle, |
63 MojoHandle* platform_handle_wrapper_handle); | 60 MojoHandle* platform_handle_wrapper_handle); |
64 | 61 |
65 // Retrieves the |PlatformHandle| that was wrapped into a |MojoHandle| (using | 62 // Retrieves the |PlatformHandle| that was wrapped into a |MojoHandle| (using |
66 // |CreatePlatformHandleWrapper()| above). Note that the |MojoHandle| must still | 63 // |CreatePlatformHandleWrapper()| above). Note that the |MojoHandle| must still |
67 // be closed separately. | 64 // be closed separately. |
68 MOJO_SYSTEM_IMPL_EXPORT MojoResult | 65 MojoResult PassWrappedPlatformHandle(MojoHandle platform_handle_wrapper_handle, |
69 PassWrappedPlatformHandle(MojoHandle platform_handle_wrapper_handle, | 66 ScopedPlatformHandle* platform_handle); |
70 ScopedPlatformHandle* platform_handle); | |
71 | 67 |
72 // Initialialization/shutdown for interprocess communication (IPC) ------------- | 68 // Initialialization/shutdown for interprocess communication (IPC) ------------- |
73 | 69 |
74 // |InitIPCSupport()| sets up the subsystem for interprocess communication, | 70 // |InitIPCSupport()| sets up the subsystem for interprocess communication, |
75 // making the IPC functions (in the following section) available and functional. | 71 // making the IPC functions (in the following section) available and functional. |
76 // (This may only be done after |Init()|.) | 72 // (This may only be done after |Init()|.) |
77 // | 73 // |
78 // This subsystem may be shut down, using |ShutdownIPCSupportOnIOThread()| or | 74 // This subsystem may be shut down, using |ShutdownIPCSupportOnIOThread()| or |
79 // |ShutdownIPCSupport()|. None of the IPC functions may be called while or | 75 // |ShutdownIPCSupport()|. None of the IPC functions may be called while or |
80 // after either of these is called. | 76 // after either of these is called. |
81 | 77 |
82 // Initializes a process of the given type; to be called after |Init()|. | 78 // Initializes a process of the given type; to be called after |Init()|. |
83 // - |process_delegate| must be a process delegate of the appropriate type | 79 // - |process_delegate| must be a process delegate of the appropriate type |
84 // corresponding to |process_type|; its methods will be called on | 80 // corresponding to |process_type|; its methods will be called on |
85 // |delegate_thread_task_runner|. | 81 // |delegate_thread_task_runner|. |
86 // - |delegate_thread_task_runner|, |process_delegate|, and | 82 // - |delegate_thread_task_runner|, |process_delegate|, and |
87 // |io_thread_task_runner| should live at least until | 83 // |io_thread_task_runner| should live at least until |
88 // |ShutdownIPCSupport()|'s callback has been run or | 84 // |ShutdownIPCSupport()|'s callback has been run or |
89 // |ShutdownIPCSupportOnIOThread()| has completed. | 85 // |ShutdownIPCSupportOnIOThread()| has completed. |
90 // - For slave processes (i.e., |process_type| is |ProcessType::SLAVE|), | 86 // - For slave processes (i.e., |process_type| is |ProcessType::SLAVE|), |
91 // |platform_handle| should be connected to the handle passed to | 87 // |platform_handle| should be connected to the handle passed to |
92 // |ConnectToSlave()| (in the master process). For other processes, | 88 // |ConnectToSlave()| (in the master process). For other processes, |
93 // |platform_handle| is ignored (and should not be valid). | 89 // |platform_handle| is ignored (and should not be valid). |
94 MOJO_SYSTEM_IMPL_EXPORT void InitIPCSupport( | 90 void InitIPCSupport(ProcessType process_type, |
95 ProcessType process_type, | 91 scoped_refptr<base::TaskRunner> delegate_thread_task_runner, |
96 scoped_refptr<base::TaskRunner> delegate_thread_task_runner, | 92 ProcessDelegate* process_delegate, |
97 ProcessDelegate* process_delegate, | 93 scoped_refptr<base::TaskRunner> io_thread_task_runner, |
98 scoped_refptr<base::TaskRunner> io_thread_task_runner, | 94 ScopedPlatformHandle platform_handle); |
99 ScopedPlatformHandle platform_handle); | |
100 | 95 |
101 // Shuts down the subsystem initialized by |InitIPCSupport()|. This must be | 96 // Shuts down the subsystem initialized by |InitIPCSupport()|. This must be |
102 // called on the I/O thread (given to |InitIPCSupport()|). This completes | 97 // called on the I/O thread (given to |InitIPCSupport()|). This completes |
103 // synchronously and does not result in a call to the process delegate's | 98 // synchronously and does not result in a call to the process delegate's |
104 // |OnShutdownComplete()|. | 99 // |OnShutdownComplete()|. |
105 MOJO_SYSTEM_IMPL_EXPORT void ShutdownIPCSupportOnIOThread(); | 100 void ShutdownIPCSupportOnIOThread(); |
106 | 101 |
107 // Like |ShutdownIPCSupportOnIOThread()|, but may be called from any thread, | 102 // Like |ShutdownIPCSupportOnIOThread()|, but may be called from any thread, |
108 // signalling shutdown completion via the process delegate's | 103 // signalling shutdown completion via the process delegate's |
109 // |OnShutdownComplete()|. | 104 // |OnShutdownComplete()|. |
110 MOJO_SYSTEM_IMPL_EXPORT void ShutdownIPCSupport(); | 105 void ShutdownIPCSupport(); |
111 | 106 |
112 // Interprocess communication (IPC) functions ---------------------------------- | 107 // Interprocess communication (IPC) functions ---------------------------------- |
113 | 108 |
114 // Called in the master process to connect to a slave process to the IPC system. | 109 // Called in the master process to connect to a slave process to the IPC system. |
115 // (This should only be called in a process initialized (using | 110 // (This should only be called in a process initialized (using |
116 // |InitIPCSupport()|) with process type |ProcessType::MASTER|.) | 111 // |InitIPCSupport()|) with process type |ProcessType::MASTER|.) |
117 // | 112 // |
118 // This should typically be called *before* the slave process is even created. | 113 // This should typically be called *before* the slave process is even created. |
119 // It requires an OS "pipe" to be established between the master and slave | 114 // It requires an OS "pipe" to be established between the master and slave |
120 // processes, with |platform_handle| being a handle to the end that remains on | 115 // processes, with |platform_handle| being a handle to the end that remains on |
121 // the master. | 116 // the master. |
122 // | 117 // |
123 // This will establish a channel and an initial message pipe (to which it | 118 // This will establish a channel and an initial message pipe (to which it |
124 // returns a handle), an ID string (returned in |*platform_connection_id|) that | 119 // returns a handle), an ID string (returned in |*platform_connection_id|) that |
125 // must be passed to the slave (e.g., on the command line), and a | 120 // must be passed to the slave (e.g., on the command line), and a |
126 // |ChannelInfo*| (in |*channel_info|) which should eventually be given to | 121 // |ChannelInfo*| (in |*channel_info|) which should eventually be given to |
127 // |DestroyChannel()|/|DestroyChannelOnIOThread()|, but only after | 122 // |DestroyChannel()|/|DestroyChannelOnIOThread()|, but only after |
128 // |did_connect_to_slave_callback| has been run. | 123 // |did_connect_to_slave_callback| has been run. |
129 // | 124 // |
130 // |did_connect_to_slave_callback| will be run either using | 125 // |did_connect_to_slave_callback| will be run either using |
131 // |did_connect_to_slave_runner| (if non-null) or on the I/O thread, once the | 126 // |did_connect_to_slave_runner| (if non-null) or on the I/O thread, once the |
132 // |ChannelInfo*| is valid. | 127 // |ChannelInfo*| is valid. |
133 // | 128 // |
134 // TODO(vtl): The API is a little crazy with respect to the |ChannelInfo*|. | 129 // TODO(vtl): The API is a little crazy with respect to the |ChannelInfo*|. |
135 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle | 130 ScopedMessagePipeHandle ConnectToSlave( |
136 ConnectToSlave(SlaveInfo slave_info, | 131 SlaveInfo slave_info, |
137 ScopedPlatformHandle platform_handle, | 132 ScopedPlatformHandle platform_handle, |
138 const base::Closure& did_connect_to_slave_callback, | 133 const base::Closure& did_connect_to_slave_callback, |
139 scoped_refptr<base::TaskRunner> did_connect_to_slave_runner, | 134 scoped_refptr<base::TaskRunner> did_connect_to_slave_runner, |
140 std::string* platform_connection_id, | 135 std::string* platform_connection_id, |
141 ChannelInfo** channel_info); | 136 ChannelInfo** channel_info); |
142 | 137 |
143 // Called in a slave process to connect it to the IPC system. (This should only | 138 // Called in a slave process to connect it to the IPC system. (This should only |
144 // be called in a process initialized (using |InitIPCSupport()|) with process | 139 // be called in a process initialized (using |InitIPCSupport()|) with process |
145 // type |ProcessType::SLAVE|.) This should be called exactly once in each slave | 140 // type |ProcessType::SLAVE|.) This should be called exactly once in each slave |
146 // process. | 141 // process. |
147 // | 142 // |
148 // See |ConnectToSlave()| for details. (Note that if this fails in any way, | 143 // See |ConnectToSlave()| for details. (Note that if this fails in any way, |
149 // e.g., if |platform_connection_id| is invalid, this will CHECK-fail and | 144 // e.g., if |platform_connection_id| is invalid, this will CHECK-fail and |
150 // terminate the process.) |channel_info|, |did_connect_to_master_callback|, and | 145 // terminate the process.) |channel_info|, |did_connect_to_master_callback|, and |
151 // |did_connect_to_master_runner| are analagous to in |ConnectToSlave()|. | 146 // |did_connect_to_master_runner| are analagous to in |ConnectToSlave()|. |
152 // | 147 // |
153 // TODO(vtl): The API is a little crazy with respect to the |ChannelInfo*|. | 148 // TODO(vtl): The API is a little crazy with respect to the |ChannelInfo*|. |
154 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle | 149 ScopedMessagePipeHandle ConnectToMaster( |
155 ConnectToMaster(const std::string& platform_connection_id, | 150 const std::string& platform_connection_id, |
156 const base::Closure& did_connect_to_master_callback, | 151 const base::Closure& did_connect_to_master_callback, |
157 scoped_refptr<base::TaskRunner> did_connect_to_master_runner, | 152 scoped_refptr<base::TaskRunner> did_connect_to_master_runner, |
158 ChannelInfo** channel_info); | 153 ChannelInfo** channel_info); |
159 | 154 |
160 // A "channel" is a connection on top of an OS "pipe", on top of which Mojo | 155 // A "channel" is a connection on top of an OS "pipe", on top of which Mojo |
161 // message pipes (etc.) can be multiplexed. It must "live" on some I/O thread. | 156 // message pipes (etc.) can be multiplexed. It must "live" on some I/O thread. |
162 // | 157 // |
163 // There are two channel creation APIs: |CreateChannelOnIOThread()| creates a | 158 // There are two channel creation APIs: |CreateChannelOnIOThread()| creates a |
164 // channel synchronously and must be called from the I/O thread, while | 159 // channel synchronously and must be called from the I/O thread, while |
165 // |CreateChannel()| is asynchronous and may be called from any thread. | 160 // |CreateChannel()| is asynchronous and may be called from any thread. |
166 // |DestroyChannel()| is used to destroy the channel in either case and may be | 161 // |DestroyChannel()| is used to destroy the channel in either case and may be |
167 // called from any thread, but completes synchronously when called from the I/O | 162 // called from any thread, but completes synchronously when called from the I/O |
168 // thread. | 163 // thread. |
(...skipping 20 matching lines...) Expand all Loading... |
189 // Both also produce a |ChannelInfo*| (a pointer to an opaque object) -- the | 184 // Both also produce a |ChannelInfo*| (a pointer to an opaque object) -- the |
190 // first synchronously and second asynchronously. | 185 // first synchronously and second asynchronously. |
191 // | 186 // |
192 // The destruction functions are similarly synchronous and asynchronous, | 187 // The destruction functions are similarly synchronous and asynchronous, |
193 // respectively, and take the |ChannelInfo*| produced by the creation functions. | 188 // respectively, and take the |ChannelInfo*| produced by the creation functions. |
194 | 189 |
195 // Creates a channel; must only be called from the I/O thread. |platform_handle| | 190 // Creates a channel; must only be called from the I/O thread. |platform_handle| |
196 // should be a handle to a connected OS "pipe". Eventually (even on failure), | 191 // should be a handle to a connected OS "pipe". Eventually (even on failure), |
197 // the "out" value |*channel_info| should be passed to |DestoryChannel()| to | 192 // the "out" value |*channel_info| should be passed to |DestoryChannel()| to |
198 // tear down the channel. Returns a handle to the bootstrap message pipe. | 193 // tear down the channel. Returns a handle to the bootstrap message pipe. |
199 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle | 194 ScopedMessagePipeHandle CreateChannelOnIOThread( |
200 CreateChannelOnIOThread(ScopedPlatformHandle platform_handle, | 195 ScopedPlatformHandle platform_handle, |
201 ChannelInfo** channel_info); | 196 ChannelInfo** channel_info); |
202 | 197 |
203 // Creates a channel asynchronously; may be called from any thread. | 198 // Creates a channel asynchronously; may be called from any thread. |
204 // |platform_handle| should be a handle to a connected OS "pipe". | 199 // |platform_handle| should be a handle to a connected OS "pipe". |
205 // |did_create_channel_callback| should be the callback to call with the | 200 // |did_create_channel_callback| should be the callback to call with the |
206 // |ChannelInfo*|, which should eventually be passed to |DestroyChannel()| to | 201 // |ChannelInfo*|, which should eventually be passed to |DestroyChannel()| to |
207 // tear down the channel; the callback will be called using | 202 // tear down the channel; the callback will be called using |
208 // |did_create_channel_runner| if that is non-null, or otherwise it will be | 203 // |did_create_channel_runner| if that is non-null, or otherwise it will be |
209 // posted to the I/O thread. Returns a handle to the bootstrap message pipe. | 204 // posted to the I/O thread. Returns a handle to the bootstrap message pipe. |
210 // | 205 // |
211 // Note: This should only be used to establish a channel with a process of type | 206 // Note: This should only be used to establish a channel with a process of type |
212 // |ProcessType::NONE|. This function may be removed in the future. | 207 // |ProcessType::NONE|. This function may be removed in the future. |
213 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle CreateChannel( | 208 ScopedMessagePipeHandle CreateChannel( |
214 ScopedPlatformHandle platform_handle, | 209 ScopedPlatformHandle platform_handle, |
215 const base::Callback<void(ChannelInfo*)>& did_create_channel_callback, | 210 const base::Callback<void(ChannelInfo*)>& did_create_channel_callback, |
216 scoped_refptr<base::TaskRunner> did_create_channel_runner); | 211 scoped_refptr<base::TaskRunner> did_create_channel_runner); |
217 | 212 |
218 // Destroys a channel that was created using |ConnectToMaster()|, | 213 // Destroys a channel that was created using |ConnectToMaster()|, |
219 // |ConnectToSlave()|, |CreateChannel()|, or |CreateChannelOnIOThread()|; must | 214 // |ConnectToSlave()|, |CreateChannel()|, or |CreateChannelOnIOThread()|; must |
220 // be called from the channel's I'O thread. Completes synchronously (and posts | 215 // be called from the channel's I'O thread. Completes synchronously (and posts |
221 // no tasks). | 216 // no tasks). |
222 MOJO_SYSTEM_IMPL_EXPORT void DestroyChannelOnIOThread( | 217 void DestroyChannelOnIOThread(ChannelInfo* channel_info); |
223 ChannelInfo* channel_info); | |
224 | 218 |
225 // Like |DestroyChannelOnIOThread()|, but asynchronous and may be called from | 219 // Like |DestroyChannelOnIOThread()|, but asynchronous and may be called from |
226 // any thread. The callback will be called using |did_destroy_channel_runner| | 220 // any thread. The callback will be called using |did_destroy_channel_runner| |
227 // if that is non-null, or otherwise it will be called on the "channel thread". | 221 // if that is non-null, or otherwise it will be called on the "channel thread". |
228 // The "channel thread" must remain alive and continue to process tasks until | 222 // The "channel thread" must remain alive and continue to process tasks until |
229 // the callback has been executed. | 223 // the callback has been executed. |
230 MOJO_SYSTEM_IMPL_EXPORT void DestroyChannel( | 224 void DestroyChannel(ChannelInfo* channel_info, |
231 ChannelInfo* channel_info, | 225 const base::Closure& did_destroy_channel_callback, |
232 const base::Closure& did_destroy_channel_callback, | 226 scoped_refptr<base::TaskRunner> did_destroy_channel_runner); |
233 scoped_refptr<base::TaskRunner> did_destroy_channel_runner); | |
234 | 227 |
235 // Inform the channel that it will soon be destroyed (doing so is optional). | 228 // Inform the channel that it will soon be destroyed (doing so is optional). |
236 // This may be called from any thread, but the caller must ensure that this is | 229 // This may be called from any thread, but the caller must ensure that this is |
237 // called before |DestroyChannel()|. | 230 // called before |DestroyChannel()|. |
238 MOJO_SYSTEM_IMPL_EXPORT void WillDestroyChannelSoon(ChannelInfo* channel_info); | 231 void WillDestroyChannelSoon(ChannelInfo* channel_info); |
239 | 232 |
240 } // namespace embedder | 233 } // namespace embedder |
241 } // namespace mojo | 234 } // namespace mojo |
242 | 235 |
243 #endif // MOJO_EDK_EMBEDDER_EMBEDDER_H_ | 236 #endif // MOJO_EDK_EMBEDDER_EMBEDDER_H_ |
OLD | NEW |