Mojo For Chromium Developers

Overview

This document contains the minimum amount of information needed for a developer to start using Mojo in Chromium. For more detailed documentation on the C++ bindings, see this link.

Terminology

A message pipe is a pair of endpoints. Each endpoint has a queue of incoming messages, and writing a message to one endpoint effectively enqueues that message on the other endpoint. Message pipes are thus bidirectional.

A mojom file describes interfaces which describe strongly typed message structures, similar to proto files.

Given a mojom interface and a message pipe, the two endpoints can be given the labels InterfacePtr and Binding. This now describes a strongly typed message pipe which transports messages described by the mojom interface. The InterfacePtr is the endpoint which “sends” messages, and the Binding “receives” messages. Note that the message pipe itself is still bidirectional, and it's possible for a message to have a response callback, which the InterfacePtr would receive.

Another way to think of this is that an InterfacePtr is capable of making remote calls on an implementation of the mojom interface associated with the Binding.

The Binding itself is just glue that wires the endpoint's message queue up to some implementation of the interface provided by the developer.

Example

Let‘s apply this to Chrome. Let’s say we want to send a “Ping” message from a Browser to a Renderer. First we need to define the mojom interface.

module example.mojom;
interface PingResponder {
  // Receives a "Ping" and responds with a random integer.
  Ping() => (int random);
};

Now let's make a MessagePipe.

example::mojom::PingResponderPtr ping_responder;
example::mojom::PingResponderRequest request = mojo::MakeRequest(&ping_responder);

In this example, ping_responder is the InterfacePtr, and request is an InterfaceRequest, which is a Binding precursor that will shortly be turned into a Binding. Now we can send our Ping message.

auto callback = base::Bind(&OnPong);
ping_responder->Ping(callback);

Important aside: If we want to receive the the response, we must keep the object ping_responder alive. After all, it‘s just a wrapper around a Message Pipe endpoint, if it were to go away, there’d be nothing left to receive the response.

We‘re done! Of course, if everything were this easy, this document wouldn’t need to exist. We've taken the hard problem of sending a message from the Browser to a Renderer, and transformed it into a problem where we just need to take the request object, pass it to the Renderer, turn it into a Binding, and implement the interface.

In Chrome, processes host services, and the services themselves are connected to a Service Manager via message pipes. It‘s easy to pass request to the appropriate Renderer using the Service Manager, but this requires explicitly declaring our intentions via manifest files. For this example, we’ll use the content_browser service manifest file and the content_renderer service manifest file.

content_renderer_manifest.json:
...
  "interface_provider_specs": {
    "service_manager:connector": {
      "provides": {
        "cool_ping_feature": [
          "example::mojom::PingResponder"
        ]
      },
    },
...

content_browser_manifest.json:
...
 "interface_provider_specs": {
    "service_manager:connector": {
      "requires": {
        "content_renderer": [ "cool_ping_feature" ],
      },
    },
  },
...

These changes indicate that the content_renderer service provides the interface PingResponder, under the capability named “cool_ping_feature”. And the content_browser services intends to use this feature. content::BindInterface is a helper function that takes request and sends it to the renderer process via the Service Manager.

content::RenderProcessHost* host = GetRenderProcessHost();
content::BindInterface(host, std::move(request));

Putting this all together for the browser process:

example::mojom::PingResponderPtr ping_responder;  // Make sure to keep this alive! Otherwise the response will never be received.
example::mojom::PingResponderRequest request = mojo::MakeRequest(&ping_responder);
ping_responder->Ping(base::BindOnce(&OnPong));
content::RenderProcessHost* host = GetRenderProcessHost();
content::BindInterface(host, std::move(request));

In the Renderer process, we need to write an implementation for PingResponder, and ensure that a Binding is created using the transported request. In a standalone Mojo service, this would require us to implement service_manager::Service::OnBindInterface(). In Chrome, this is abstracted behind content::ConnectionFilters and service_manager::BinderRegistry. This is typically done in RenderThreadImpl::Init.

class PingResponderImpl : mojom::PingResponder {
  void BindToInterface(example::mojom::PingResponderRequest request) {
    binding_.reset(
      new mojo::Binding<mojom::MemlogClient>(this, std::move(request)));
  }
  void Ping(PingCallback callback) { std::move(callback).Run(4); }
  std::unique_ptr<mojo::Binding<mojom::PingResponder>> binding_;
};

RenderThreadImpl::Init() {
...
  this->ping_responder = std::make_unique<PingResponderImpl>();
  auto registry = base::MakeUnique<service_manager::BinderRegistry>();

  // This makes the assumption that |this->ping_responder| will outlive |registry|.
  registry->AddInterface(base::Bind(&PingResponderImpl::BindToInterface), base::Unretained(this->ping_responder.get()));

  GetServiceManagerConnection()->AddConnectionFilter(
      base::MakeUnique<SimpleConnectionFilter>(std::move(registry)));
...