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_PUBLIC_CPP_BINDINGS_BINDING_H_ | |
6 #define MOJO_PUBLIC_CPP_BINDINGS_BINDING_H_ | |
7 | |
8 #include <mojo/environment/async_waiter.h> | |
9 | |
10 #include <memory> | |
11 #include <utility> | |
12 | |
13 #include "mojo/public/cpp/bindings/callback.h" | |
14 #include "mojo/public/cpp/bindings/interface_handle.h" | |
15 #include "mojo/public/cpp/bindings/interface_ptr.h" | |
16 #include "mojo/public/cpp/bindings/interface_request.h" | |
17 #include "mojo/public/cpp/bindings/lib/message_header_validator.h" | |
18 #include "mojo/public/cpp/bindings/lib/router.h" | |
19 #include "mojo/public/cpp/environment/logging.h" | |
20 #include "mojo/public/cpp/system/macros.h" | |
21 #include "mojo/public/cpp/system/message_pipe.h" | |
22 | |
23 namespace mojo { | |
24 | |
25 // Represents the binding of an interface implementation to a message pipe. | |
26 // When the |Binding| object is destroyed, the binding between the message pipe | |
27 // and the interface is torn down and the message pipe is closed, leaving the | |
28 // interface implementation in an unbound state. | |
29 // | |
30 // Example: | |
31 // | |
32 // #include "foo.mojom.h" | |
33 // | |
34 // class FooImpl : public Foo { | |
35 // public: | |
36 // explicit FooImpl(InterfaceRequest<Foo> request) | |
37 // : binding_(this, request.Pass()) {} | |
38 // | |
39 // // Foo implementation here. | |
40 // | |
41 // private: | |
42 // Binding<Foo> binding_; | |
43 // }; | |
44 // | |
45 // The caller may specify a |MojoAsyncWaiter| to be used by the connection when | |
46 // waiting for calls to arrive. Normally it is fine to use the default waiter. | |
47 // However, the caller may provide their own implementation if needed. The | |
48 // |Binding| will not take ownership of the waiter, and the waiter must outlive | |
49 // the |Binding|. The provided waiter must be able to signal the implementation | |
50 // which generally means it needs to be able to schedule work on the thread the | |
51 // implementation runs on. If writing library code that has to work on different | |
52 // types of threads callers may need to provide different waiter | |
53 // implementations. | |
54 template <typename Interface> | |
55 class Binding { | |
56 public: | |
57 // Constructs an incomplete binding that will use the implementation |impl|. | |
58 // The binding may be completed with a subsequent call to the |Bind| method. | |
59 // Does not take ownership of |impl|, which must outlive the binding. | |
60 explicit Binding(Interface* impl) : impl_(impl) { stub_.set_sink(impl_); } | |
61 | |
62 // Constructs a completed binding of message pipe |handle| to implementation | |
63 // |impl|. Does not take ownership of |impl|, which must outlive the binding. | |
64 // See class comment for definition of |waiter|. | |
65 Binding(Interface* impl, | |
66 ScopedMessagePipeHandle handle, | |
67 const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) | |
68 : Binding(impl) { | |
69 Bind(handle.Pass(), waiter); | |
70 } | |
71 | |
72 // Constructs a completed binding of |impl| to a new message pipe, passing the | |
73 // client end to |ptr|, which takes ownership of it. The caller is expected to | |
74 // pass |ptr| on to the client of the service. Does not take ownership of any | |
75 // of the parameters. |impl| must outlive the binding. |ptr| only needs to | |
76 // last until the constructor returns. See class comment for definition of | |
77 // |waiter|. | |
78 Binding(Interface* impl, | |
79 InterfaceHandle<Interface>* interface_handle, | |
80 const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) | |
81 : Binding(impl) { | |
82 Bind(interface_handle, waiter); | |
83 } | |
84 | |
85 // Constructs a completed binding of |impl| to the message pipe endpoint in | |
86 // |request|, taking ownership of the endpoint. Does not take ownership of | |
87 // |impl|, which must outlive the binding. See class comment for definition of | |
88 // |waiter|. | |
89 Binding(Interface* impl, | |
90 InterfaceRequest<Interface> request, | |
91 const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) | |
92 : Binding(impl) { | |
93 Bind(request.PassMessagePipe(), waiter); | |
94 } | |
95 | |
96 // Tears down the binding, closing the message pipe and leaving the interface | |
97 // implementation unbound. | |
98 ~Binding() {} | |
99 | |
100 // Completes a binding that was constructed with only an interface | |
101 // implementation. Takes ownership of |handle| and binds it to the previously | |
102 // specified implementation. See class comment for definition of |waiter|. | |
103 void Bind( | |
104 ScopedMessagePipeHandle handle, | |
105 const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) { | |
106 MOJO_DCHECK(!internal_router_); | |
107 | |
108 internal::MessageValidatorList validators; | |
109 validators.push_back(std::unique_ptr<internal::MessageValidator>( | |
110 new internal::MessageHeaderValidator)); | |
111 validators.push_back(std::unique_ptr<internal::MessageValidator>( | |
112 new typename Interface::RequestValidator_)); | |
113 | |
114 internal_router_.reset( | |
115 new internal::Router(std::move(handle), std::move(validators), waiter)); | |
116 internal_router_->set_incoming_receiver(&stub_); | |
117 internal_router_->set_connection_error_handler( | |
118 [this]() { connection_error_handler_.Run(); }); | |
119 } | |
120 | |
121 // Completes a binding that was constructed with only an interface | |
122 // implementation by creating a new message pipe, binding one end of it to the | |
123 // previously specified implementation, and passing the other to |ptr|, which | |
124 // takes ownership of it. The caller is expected to pass |ptr| on to the | |
125 // eventual client of the service. Does not take ownership of |ptr|. See | |
126 // class comment for definition of |waiter|. | |
127 void Bind( | |
128 InterfaceHandle<Interface>* interface_handle, | |
129 const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) { | |
130 MessagePipe pipe; | |
131 *interface_handle = | |
132 InterfaceHandle<Interface>(pipe.handle0.Pass(), Interface::Version_); | |
133 Bind(pipe.handle1.Pass(), waiter); | |
134 } | |
135 | |
136 // Completes a binding that was constructed with only an interface | |
137 // implementation by removing the message pipe endpoint from |request| and | |
138 // binding it to the previously specified implementation. See class comment | |
139 // for definition of |waiter|. | |
140 void Bind( | |
141 InterfaceRequest<Interface> request, | |
142 const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) { | |
143 Bind(request.PassMessagePipe(), waiter); | |
144 } | |
145 | |
146 // Blocks the calling thread until either a call arrives on the previously | |
147 // bound message pipe, the deadline is exceeded, or an error occurs. Returns | |
148 // true if a method was successfully read and dispatched. | |
149 bool WaitForIncomingMethodCall( | |
150 MojoDeadline deadline = MOJO_DEADLINE_INDEFINITE) { | |
151 MOJO_DCHECK(internal_router_); | |
152 return internal_router_->WaitForIncomingMessage(deadline); | |
153 } | |
154 | |
155 // Closes the message pipe that was previously bound. Put this object into a | |
156 // state where it can be rebound to a new pipe. | |
157 void Close() { | |
158 MOJO_DCHECK(internal_router_); | |
159 internal_router_.reset(); | |
160 } | |
161 | |
162 // Unbinds the underlying pipe from this binding and returns it so it can be | |
163 // used in another context, such as on another thread or with a different | |
164 // implementation. Put this object into a state where it can be rebound to a | |
165 // new pipe. | |
166 InterfaceRequest<Interface> Unbind() { | |
167 auto request = | |
168 InterfaceRequest<Interface>(internal_router_->PassMessagePipe()); | |
169 internal_router_.reset(); | |
170 return request; | |
171 } | |
172 | |
173 // Sets an error handler that will be called if a connection error occurs on | |
174 // the bound message pipe. | |
175 void set_connection_error_handler(const Closure& error_handler) { | |
176 connection_error_handler_ = error_handler; | |
177 } | |
178 | |
179 // Returns the interface implementation that was previously specified. Caller | |
180 // does not take ownership. | |
181 Interface* impl() { return impl_; } | |
182 | |
183 // Indicates whether the binding has been completed (i.e., whether a message | |
184 // pipe has been bound to the implementation). | |
185 bool is_bound() const { return !!internal_router_; } | |
186 | |
187 // Returns the value of the handle currently bound to this Binding which can | |
188 // be used to make explicit Wait/WaitMany calls. Requires that the Binding be | |
189 // bound. Ownership of the handle is retained by the Binding, it is not | |
190 // transferred to the caller. | |
191 MessagePipeHandle handle() const { | |
192 MOJO_DCHECK(is_bound()); | |
193 return internal_router_->handle(); | |
194 } | |
195 | |
196 // Exposed for testing, should not generally be used. | |
197 internal::Router* internal_router() { return internal_router_.get(); } | |
198 | |
199 private: | |
200 std::unique_ptr<internal::Router> internal_router_; | |
201 typename Interface::Stub_ stub_; | |
202 Interface* impl_; | |
203 Closure connection_error_handler_; | |
204 | |
205 MOJO_DISALLOW_COPY_AND_ASSIGN(Binding); | |
206 }; | |
207 | |
208 } // namespace mojo | |
209 | |
210 #endif // MOJO_PUBLIC_CPP_BINDINGS_BINDING_H_ | |
OLD | NEW |