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