Mojo Associated Interfaces
02/22/2017
Background
Before associated interfaces are introduced, each Mojo interface is always run on a separate message pipe, so there is no ordering guarantee between different interfaces. It could cause difficulties for using a set of semantically related interfaces. For example, consider the following call sequence:
file_ptr->Append(...);
file_system_ptr->GetUsedSpace(...);
Even if the impls of both interfaces live on the same process and thread, the arriving order of Append() and GetUsedSpace() is undefined. Another example:
// Run a callback of the File interface and send an event using the
// corresponding FileClient interface.
file_append_callback.Run(...);
file_client_ptr->NotifyFileSizeChanged(...);
Again, the arriving order of the callback and NotifyFileSizeChanged() is undefined.
This is not only counterintuitive, but also likely to have a negative impact on API design. With lack of ordering, developers are more inclined to define a monolithic interface for a logical grouping of functionality, rather than properly splitting the functionality into multiple interfaces.
Associated interfaces are used to solve this “FIFO” problem. It enables running multiple interfaces over a single message pipe. It also allows the bindings to use a single message pipe from multiple threads.
Overview
When a message pipe is created to run an interface, the interface is called the master interface for the message pipe. Associated interfaces can be set up on the same message pipe. Each message pipe can have an arbitrary number of associated interfaces but always a single master interface. The impl side of associated interfaces can live at either end of the message pipe.
Each interface is assigned an interface ID. The ID is scoped to the message pipe. Messages have an interface ID field so that they can be routed to the corresponding interface.
For the sake of convenience, the document refers to both the impl and client side of an interface as interface endpoints.
The work of setting up an associated interface includes allocating an interface ID; setting up an interface endpoint at one end of the message pipe; passing the ID over the message pipe; and setting up the corresponding interface endpoint there. From a user’s point of view, he/she creates a pair of AssociatedInterfacePtrInfo and AssociatedInterfaceRequest, binds one of them to Associated{InterfacePtr|Binding} locally, passes the other using another interface (either master or associated) to the remote side.
The following figure shows a message pipe running multiple interfaces.
In the figure above, either direction of the message pipe is a FIFO queue and therefore preserves message order:
-
right -> left: master and associated_2 method calls, associated_1 callbacks.
-
left -> right: master and associated_2 callbacks, associated_1 method calls.
Although each interface should be used strictly on a single thread, using master and associated interfaces on different threads is allowed. FIFO-ness is still preserved in this case. For example: Master sends message_1 and then signals assciated_1 (living on another thread) to send message_2. Message_1 and message_2 are guaranteed to arrive at the other end in order.
Because associated interfaces don’t have their own message pipes, there are some important restrictions:
-
At either end of the message pipe, the code for the master and associated interfaces must live in the same process.
-
Associated interface pointers and requests cannot be passed back over the same message pipe or forwarded over a different message pipe.
-
Extracting the underlying message pipe handles for the master interface is allowed, but it closes any existing associated interfaces.
-
It is disallowed to make calls on an associated interface foo_ptr before the associated interface request foo_request is sent. Doing so is considered as a programming error which could lead to crash or message pipe being closed. This restriction is required by the FIFO-ness guarantee: when receiving a message of foo method calls, we want to dispatch it to the foo impl before processing any subsequent messages. If foo_request is in a subsequent message, message dispatching gets into a deadlock.
On the other hand, as soon as foo_request is sent, foo_ptr is usable. There is no need to wait until foo_request is bound with an impl. If a message of foo method calls arrives before foo_request is bound, the message (and any subsequent messages) needs to be queued.
Mojom
A new keyword associated is introduced for interface pointers or requests. For example:
struct Qux {
associated Bar bar3;
};
interface Foo {
SetBar(associated Bar bar1);
GetBar(associated Bar& bar2);
PassQux(Qux qux);
};
bar1/bar2/bar3 are all associated with the message pipe on which they are passed.
Message format
The message header definition is changed to:
struct MessageHeader {
uint32 interface_id;
uint32 type;
uint32 flags;
[MinVersion=1] uint64 request_id;
[MinVersion=2] GenericStruct payload;
[MinVersion=2] array<uint32> payload_interface_ids;
};
The interface_id field indicates which interface the message should be routed to.
If a message transfers associated interface pointers or requests, it needs to use message header struct version 2 (or above). The payload field points to the payload struct. The payload_interface_ids field points to a mojo array of uint32 containing all interface IDs transferred.
In the message payload, an associated interface pointer is encoded as a uint32 index into the payload_interface_ids array + a uint32 version field; an associated interface request is encoded as a uint32 index into the payload_interface_ids array.
Why do we need the payload_interface_ids array? Why don’t we put interface IDs directly in the payload? If a message is discarded, or contains fields that are not understood due to version difference, the router wants to know what interface IDs are abandoned, in order to notify the sender side to raise connection error on the corresponding interface endpoints. Please consider the following example:
(1) The user creates AssociatedInterfacePtr<Foo> foo_ptr and AssociatedInterfaceRequest<Foo> foo_request.
(2) He sends foo_request over the message pipe, using a method call on another interface bar_ptr.
(3) At the other side, bar_binding is closed before it accepts the method call containing foo_request, so the corresponding message is discarded by the router.
(4) The router wants to notify the sending side to raise a connection error on foo_ptr.
Interface ID allocation
-
Interface IDs are scoped to the message pipe they are used on.
-
0 is the master interface ID; 0xFFFFFFFF is the invalid ID.
-
IDs of associated interface can be generated at both sides of the message pipe. In order to avoid collision, the highest bit is used as namespace bit: at the side where the client-side of the master interface lives, IDs are generated with the namespace bit set to 1; at the opposite side IDs are generated with the namespace bit set to 0.
Control messages
Because closing the client/impl side of an associated interface doesn’t result in message pipe disconnection, we need control messages to notify its peer. There are two control messages:
NotifyPeerEndpointClosed: Notifies that an interface endpoint set up at the message sender side has been closed. It carries an interface ID as payload, as well as an optional disconnect reason.
NotifyPeerEndpointClosed is pretty straightforward. Please consider the following example:
(1) The user creates AssociatedInterfacePtr<Foo> foo_ptr and AssociatedInterfaceRequest<Foo> foo_request. Assume the interface ID is foo_id.
(2) He sends foo_request over the message pipe, which is then bound to foo_binding.
(3) foo_ptr is closed.
(4) foo_binding is closed.
The following is the message sequence and the bookkeeping inside the message routers at both sides:
Performance considerations
When using associated interfaces on threads different than the master thread (where the master interface lives):
-
Sending messages: send happens directly on the calling thread. So there shouldn’t be performance penalty except the locking operation in router/connector.
-
Receiving messages: the router listens on the master thread, therefore there will be one extra thread hop. This cannot be overcomed with the current mojo system API. If later we decide to remove this extra hop, we will need to invent new system api or push this feature downwards into the system layer.
Therefore, performance-wise associated interfaces are better suited for scenarios where message receiving happens on the master thread:
Bindings (C++)
This document shows how to use associated interfaces in C++.