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_EMBEDDER_EMBEDDER_H_ | 5 #ifndef MOJO_EMBEDDER_EMBEDDER_H_ |
6 #define MOJO_EMBEDDER_EMBEDDER_H_ | 6 #define MOJO_EMBEDDER_EMBEDDER_H_ |
7 | 7 |
8 #include "base/callback.h" | 8 #include "base/callback.h" |
9 #include "base/memory/ref_counted.h" | 9 #include "base/memory/ref_counted.h" |
10 #include "base/task_runner.h" | 10 #include "base/task_runner.h" |
11 #include "mojo/embedder/scoped_platform_handle.h" | 11 #include "mojo/embedder/scoped_platform_handle.h" |
12 #include "mojo/public/cpp/system/core.h" | 12 #include "mojo/public/cpp/system/core.h" |
13 #include "mojo/system/system_impl_export.h" | 13 #include "mojo/system/system_impl_export.h" |
14 | 14 |
15 namespace mojo { | 15 namespace mojo { |
16 namespace embedder { | 16 namespace embedder { |
17 | 17 |
18 // Must be called first to initialize the (global, singleton) system. | 18 // Must be called first to initialize the (global, singleton) system. |
19 MOJO_SYSTEM_IMPL_EXPORT void Init(); | 19 MOJO_SYSTEM_IMPL_EXPORT void Init(); |
20 | 20 |
21 // Creates a new "channel", returning a handle to the bootstrap message pipe on | 21 // A "channel" is a connection on top of an OS "pipe", on top of which Mojo |
22 // that channel. |platform_handle| should be an OS-dependent handle to one side | 22 // message pipes (etc.) can be multiplexed. It must "live" on some I/O thread. |
23 // of a suitable bidirectional OS "pipe" (e.g., a file descriptor to a socket on | |
24 // POSIX, a handle to a named pipe on Windows); this "pipe" should be connected | |
25 // and ready for operation (e.g., to be written to or read from). | |
26 // |io_thread_task_runner| should be a |TaskRunner| for the thread on which the | |
27 // "channel" will run (read data and demultiplex). | |
28 // | 23 // |
29 // On completion, it will run |callback| with a pointer to a |ChannelInfo| | 24 // There are two "channel" creation/destruction APIs: the synchronous |
30 // (which is meant to be opaque to the embedder). If | 25 // |CreateChannelOnIOThread()|/|DestroyChannelOnIOThread()|, which must be |
31 // |callback_thread_task_runner| is non-null, it the callback will be posted to | 26 // called from the I/O thread, and the asynchronous |
32 // that task runner. Otherwise, it will be run on the I/O thread directly. | 27 // |CreateChannel()|/|DestroyChannel()|, which may be called from any thread. |
33 // | 28 // |
34 // Returns an invalid |MOJO_HANDLE_INVALID| on error. Note that this will happen | 29 // Both creation functions have a |platform_handle| argument, which should be an |
35 // only if, e.g., the handle table is full (operation of the channel begins | 30 // OS-dependent handle to one side of a suitable bidirectional OS "pipe" (e.g., |
36 // asynchronously and if, e.g., the other end of the "pipe" is closed, this will | 31 // a file descriptor to a socket on POSIX, a handle to a named pipe on Windows); |
37 // report an error to the returned handle in the usual way). | 32 // this "pipe" should be connected and ready for operation (e.g., to be written |
| 33 // to or read from). |
38 // | 34 // |
39 // Notes: The handle returned is ready for use immediately, with messages | 35 // Both (synchronously) return a handle to the bootstrap message pipe on the |
40 // written to it queued. E.g., it would be perfectly valid for a message to be | 36 // channel that was (or is to be) created, or |MOJO_HANDLE_INVALID| on error |
41 // immediately written to the returned handle and the handle closed, all before | 37 // (but note that this will happen only if, e.g., the handle table is full). |
42 // the channel has begun operation on the IO thread. In this case, the channel | 38 // This message pipe may be used immediately, but since channel operation |
43 // is expected to connect as usual, send the queued message, and report that the | 39 // actually begins asynchronously, other errors may still occur (e.g., if the |
44 // handle was closed to the other side. (This message may well contain another | 40 // other end of the "pipe" is closed) and be reported in the usual way to the |
45 // handle, so there may well still be message pipes "on" this channel.) | 41 // returned handle. |
| 42 // |
| 43 // (E.g., a message written immediately to the returned handle will be queued |
| 44 // and the handle immediately closed, before the channel begins operation. In |
| 45 // this case, the channel should connect as usual, send the queued message, and |
| 46 // report that the handle was closed to the other side. The message sent may |
| 47 // have other handles, so there may still be message pipes "on" this channel.) |
| 48 // |
| 49 // Both also produce a |ChannelInfo*| (a pointer to an opaque object) -- the |
| 50 // first synchronously and second asynchronously. |
| 51 // |
| 52 // The destruction functions are similarly synchronous and asynchronous, |
| 53 // respectively, and take the |ChannelInfo*| produced by the creation function. |
| 54 // (Note: One may call |DestroyChannelOnIOThread()| with the result of |
| 55 // |CreateChannel()|, but not |DestroyChannel()| with the result of |
| 56 // |CreateChannelOnIOThread()|.) |
46 // | 57 // |
47 // TODO(vtl): Figure out channel teardown. | 58 // TODO(vtl): Figure out channel teardown. |
48 struct ChannelInfo; | 59 struct ChannelInfo; |
| 60 |
| 61 // Creates a channel; must only be called from the I/O thread. |platform_handle| |
| 62 // should be a handle to a connected OS "pipe". Eventually (even on failure), |
| 63 // the "out" value |*channel_info| should be passed to |
| 64 // |DestroyChannelOnIOThread()| to tear down the channel. Returns a handle to |
| 65 // the bootstrap message pipe. |
| 66 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle |
| 67 CreateChannelOnIOThread(ScopedPlatformHandle platform_handle, |
| 68 ChannelInfo** channel_info); |
| 69 |
49 typedef base::Callback<void(ChannelInfo*)> DidCreateChannelCallback; | 70 typedef base::Callback<void(ChannelInfo*)> DidCreateChannelCallback; |
| 71 // Creates a channel asynchronously; may be called from any thread. |
| 72 // |platform_handle| should be a handle to a connected OS "pipe". |
| 73 // |io_thread_task_runner| should be the |TaskRunner| for the I/O thread. |
| 74 // |callback| should be the callback to call with the |ChannelInfo*|, which |
| 75 // should eventually be passed to |DestroyChannel()| (or |
| 76 // |DestroyChannelOnIOThread()|) to tear down the channel; the callback will be |
| 77 // called using |callback_thread_task_runner| if that is non-null, or otherwise |
| 78 // it will be called using |io_thread_task_runner|. Returns a handle to the |
| 79 // bootstrap message pipe. |
50 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle | 80 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle |
51 CreateChannel(ScopedPlatformHandle platform_handle, | 81 CreateChannel(ScopedPlatformHandle platform_handle, |
52 scoped_refptr<base::TaskRunner> io_thread_task_runner, | 82 scoped_refptr<base::TaskRunner> io_thread_task_runner, |
53 DidCreateChannelCallback callback, | 83 DidCreateChannelCallback callback, |
54 scoped_refptr<base::TaskRunner> callback_thread_task_runner); | 84 scoped_refptr<base::TaskRunner> callback_thread_task_runner); |
55 | 85 |
| 86 // Destroys a channel that was created using either |CreateChannelOnIOThread()| |
| 87 // or |CreateChannel()|; must only be called from the I/O thread. |channel_info| |
| 88 // should be the "out" value from |CreateChannelOnIOThread()| or the value |
| 89 // provided to the callback to |CreateChannel()|. |
56 MOJO_SYSTEM_IMPL_EXPORT void DestroyChannelOnIOThread( | 90 MOJO_SYSTEM_IMPL_EXPORT void DestroyChannelOnIOThread( |
57 ChannelInfo* channel_info); | 91 ChannelInfo* channel_info); |
58 | 92 |
| 93 // Destroys a channel (asynchronously) that was created using |CreateChannel()| |
| 94 // (note: NOT |CreateChannelOnIOThread()|); may be called from any thread. |
| 95 // |channel_info| should be the value provided to the callback to |
| 96 // |CreateChannel()|. |
| 97 MOJO_SYSTEM_IMPL_EXPORT void DestroyChannel(ChannelInfo* channel_info); |
| 98 |
59 // Creates a |MojoHandle| that wraps the given |PlatformHandle| (taking | 99 // Creates a |MojoHandle| that wraps the given |PlatformHandle| (taking |
60 // ownership of it). This |MojoHandle| can then, e.g., be passed through message | 100 // ownership of it). This |MojoHandle| can then, e.g., be passed through message |
61 // pipes. Note: This takes ownership (and thus closes) |platform_handle| even on | 101 // pipes. Note: This takes ownership (and thus closes) |platform_handle| even on |
62 // failure, which is different from what you'd expect from a Mojo API, but it | 102 // failure, which is different from what you'd expect from a Mojo API, but it |
63 // makes for a more convenient embedder API. | 103 // makes for a more convenient embedder API. |
64 MOJO_SYSTEM_IMPL_EXPORT MojoResult | 104 MOJO_SYSTEM_IMPL_EXPORT MojoResult |
65 CreatePlatformHandleWrapper(ScopedPlatformHandle platform_handle, | 105 CreatePlatformHandleWrapper(ScopedPlatformHandle platform_handle, |
66 MojoHandle* platform_handle_wrapper_handle); | 106 MojoHandle* platform_handle_wrapper_handle); |
67 // Retrieves the |PlatformHandle| that was wrapped into a |MojoHandle| (using | 107 // Retrieves the |PlatformHandle| that was wrapped into a |MojoHandle| (using |
68 // |CreatePlatformHandleWrapper()| above). Note that the |MojoHandle| must still | 108 // |CreatePlatformHandleWrapper()| above). Note that the |MojoHandle| must still |
69 // be closed separately. | 109 // be closed separately. |
70 MOJO_SYSTEM_IMPL_EXPORT MojoResult | 110 MOJO_SYSTEM_IMPL_EXPORT MojoResult |
71 PassWrappedPlatformHandle(MojoHandle platform_handle_wrapper_handle, | 111 PassWrappedPlatformHandle(MojoHandle platform_handle_wrapper_handle, |
72 ScopedPlatformHandle* platform_handle); | 112 ScopedPlatformHandle* platform_handle); |
73 | 113 |
74 } // namespace embedder | 114 } // namespace embedder |
75 } // namespace mojo | 115 } // namespace mojo |
76 | 116 |
77 #endif // MOJO_EMBEDDER_EMBEDDER_H_ | 117 #endif // MOJO_EMBEDDER_EMBEDDER_H_ |
OLD | NEW |