This document is a subset of the Mojo documentation.
The Mojo C++ Bindings API leverages the C++ System API to provide a more natural set of primitives for communicating over Mojo message pipes. Combined with generated code from the Mojom IDL and bindings generator, users can easily connect interface clients and implementations across arbitrary intra- and inter-process boundaries.
This document provides a detailed guide to bindings API usage with example code snippets. For a detailed API references please consult the headers in //mojo/public/cpp/bindings.
For a simplified guide targeted at Chromium developers, see this link.
When a Mojom IDL file is processed by the bindings generator, C++ code is emitted in a series of .h
and .cc
files with names based on the input .mojom
file. Suppose we create the following Mojom file at //services/db/public/mojom/db.mojom
:
module db.mojom; interface Table { AddRow(int32 key, string data); }; interface Database { CreateTable(Table& table); };
And a GN target to generate the bindings in //services/db/public/mojom/BUILD.gn
:
import("//mojo/public/tools/bindings/mojom.gni") mojom("mojom") { sources = [ "db.mojom", ] }
Ensure that any target that needs this interface depends on it, e.g. with a line like:
deps += [ '//services/db/public/mojom' ]
If we then build this target:
ninja -C out/r services/db/public/mojom
This will produce several generated source files, some of which are relevant to C++ bindings. Two of these files are:
out/gen/services/db/public/mojom/db.mojom.cc out/gen/services/db/public/mojom/db.mojom.h
You can include the above generated header in your sources in order to use the definitions therein:
#include "services/business/public/mojom/factory.mojom.h" class TableImpl : public db::mojom::Table { // ... };
This document covers the different kinds of definitions generated by Mojom IDL for C++ consumers and how they can effectively be used to communicate across message pipes.
Mojom IDL interfaces are translated to corresponding C++ (pure virtual) class interface definitions in the generated header, consisting of a single generated method signature for each request message on the interface. Internally there is also generated code for serialization and deserialization of messages, but this detail is hidden from bindings consumers.
Let's consider a new //sample/logger.mojom
to define a simple logging interface which clients can use to log simple string messages:
module sample.mojom; interface Logger { Log(string message); };
Running this through the bindings generator will produce a logger.mojom.h
with the following definitions (modulo unimportant details):
namespace sample { namespace mojom { class Logger { virtual ~Logger() {} virtual void Log(const std::string& message) = 0; }; } // namespace mojom } // namespace sample
In the world of Mojo bindings libraries these are effectively strongly-typed message pipe endpoints. If a Remote<T>
is bound to a message pipe endpoint, it can be dereferenced to make calls on an opaque T
interface. These calls immediately serialize their arguments (using generated code) and write a corresponding message to the pipe.
A PendingReceiver<T>
is essentially just a typed container to hold the other end of a Remote<T>
‘s pipe -- the receiving end -- until it can be routed to some implementation which will bind it. The PendingReceiver<T>
doesn’t actually do anything other than hold onto a pipe endpoint and carry useful compile-time type information.
So how do we create a strongly-typed message pipe?
One way to do this is by manually creating a pipe and wrapping each end with a strongly-typed object:
#include "sample/logger.mojom.h" mojo::MessagePipe pipe; mojo::Remote<sample::mojom::Logger> logger( mojo::PendingRemote<sample::mojom::Logger>(std::move(pipe.handle0), 0)); mojo::PendingReceiver<sample::mojom::Logger> receiver(std::move(pipe.handle1));
That's pretty verbose, but the C++ Bindings library provides a more convenient way to accomplish the same thing. remote.h defines a BindNewPipeAndPassReceiver
method:
mojo::Remote<sample::mojom::Logger> logger; auto receiver = logger.BindNewPipeAndPassReceiver();
This second snippet is equivalent to the first one.
NOTE: In the first example above you may notice usage of the mojo::PendingRemote<Logger>
. This is similar to a PendingReceiver<T>
in that it merely holds onto a pipe handle and cannot actually read or write messages on the pipe. Both this type and PendingReceiver<T>
are safe to move freely from sequence to sequence, whereas a bound Remote<T>
is bound to a single sequence.
A Remote<T>
may be unbound by calling its Unbind()
method, which returns a new PendingRemote<T>
. Conversely, an Remote<T>
may bind (and thus take ownership of) an PendingRemote<T>
so that interface calls can be made on the pipe.
The sequence-bound nature of Remote<T>
is necessary to support safe dispatch of its message responses and connection error notifications.
Once the PendingRemote<Logger>
is bound we can immediately begin calling Logger
interface methods on it, which will immediately write messages into the pipe. These messages will stay queued on the receiving end of the pipe until someone binds to it and starts reading them.
logger->Log("Hello!");
This actually writes a Log
message to the pipe.
But as mentioned above, PendingReceiver
doesn't actually do anything, so that message will just sit on the pipe forever. We need a way to read messages off the other end of the pipe and dispatch them. We have to bind the pending receiver.
There are many different helper classes in the bindings library for binding the receiving end of a message pipe. The most primitive among them is mojo::Receiver<T>
. A mojo::Receiver<T>
bridges an implementation of T
with a single bound message pipe endpoint (via a mojo::PendingReceiver<T>
), which it continuously watches for readability.
Any time the bound pipe becomes readable, the Receiver
will schedule a task to read, deserialize (using generated code), and dispatch all available messages to the bound T
implementation. Below is a sample implementation of the Logger
interface. Notice that the implementation itself owns a mojo::Receiver
. This is a common pattern, since a bound implementation must outlive any mojo::Receiver
which binds it.
#include "base/logging.h" #include "sample/logger.mojom.h" class LoggerImpl : public sample::mojom::Logger { public: // NOTE: A common pattern for interface implementations which have one // instance per client is to take a PendingReceiver in the constructor. explicit LoggerImpl(mojo::PendingReceiver<sample::mojom::Logger> receiver) : receiver_(this, std::move(receiver)) {} Logger(const Logger&) = delete; Logger& operator=(const Logger&) = delete; ~Logger() override {} // sample::mojom::Logger: void Log(const std::string& message) override { LOG(ERROR) << "[Logger] " << message; } private: mojo::Receiver<sample::mojom::Logger> receiver_; };
Now we can construct a LoggerImpl
over our PendingReceiver<Logger>
, and the previously queued Log
message will be dispatched ASAP on the LoggerImpl
's sequence:
LoggerImpl impl(std::move(receiver));
The diagram below illustrates the following sequence of events, all set in motion by the above line of code:
LoggerImpl
constructor is called, passing the PendingReceiver<Logger>
along to the Receiver
.Receiver
takes ownership of the PendingReceiver<Logger>
's pipe endpoint and begins watching it for readability. The pipe is readable immediately, so a task is scheduled to read the pending Log
message from the pipe ASAP.Log
message is read and deserialized, causing the Receiver
to invoke the Logger::Log
implementation on its bound LoggerImpl
.As a result, our implementation will eventually log the client's "Hello!"
message via LOG(ERROR)
.
mojo::Receiver
in the above example) remains alive.Some Mojom interface methods expect a response. Suppose we modify our Logger
interface so that the last logged line can be queried like so:
module sample.mojom; interface Logger { Log(string message); GetTail() => (string message); };
The generated C++ interface will now look like:
namespace sample { namespace mojom { class Logger { public: virtual ~Logger() {} virtual void Log(const std::string& message) = 0; using GetTailCallback = base::OnceCallback<void(const std::string& message)>; virtual void GetTail(GetTailCallback callback) = 0; } } // namespace mojom } // namespace sample
As before, both clients and implementations of this interface use the same signature for the GetTail
method: implementations use the callback
argument to respond to the request, while clients pass a callback
argument to asynchronously receive
the response. The parameter GetTailCallback
passed to the implementation of GetTail
is sequence-affine. It must be invoked on the same sequence that GetTail
is called on. A client‘s callback
runs on the same sequence on which they invoked GetTail
(the sequence to which their logger
is bound). Here’s an updated implementation:
class LoggerImpl : public sample::mojom::Logger { public: // NOTE: A common pattern for interface implementations which have one // instance per client is to take a PendingReceiver in the constructor. explicit LoggerImpl(mojo::PendingReceiver<sample::mojom::Logger> receiver) : receiver_(this, std::move(receiver)) {} ~Logger() override {} Logger(const Logger&) = delete; Logger& operator=(const Logger&) = delete; // sample::mojom::Logger: void Log(const std::string& message) override { LOG(ERROR) << "[Logger] " << message; lines_.push_back(message); } void GetTail(GetTailCallback callback) override { std::move(callback).Run(lines_.back()); } private: mojo::Receiver<sample::mojom::Logger> receiver_; std::vector<std::string> lines_; };
And an updated client call:
void OnGetTail(const std::string& message) { LOG(ERROR) << "Tail was: " << message; } logger->GetTail(base::BindOnce(&OnGetTail));
Behind the scenes, the implementation-side callback is actually serializing the response arguments and writing them onto the pipe for delivery back to the client. Meanwhile the client-side callback is invoked by some internal logic which watches the pipe for an incoming response message, reads and deserializes it once it arrives, and then invokes the callback with the deserialized parameters.
If a pipe is disconnected, both endpoints will be able to observe the connection error (unless the disconnection is caused by closing/destroying an endpoint, in which case that endpoint won‘t get such a notification). If there are remaining incoming messages for an endpoint on disconnection, the connection error won’t be triggered until the messages are drained.
Pipe disconnection may be caused by:
mojo::Remote<T>
and it is destroyed.Regardless of the underlying cause, when a connection error is encountered on a receiver endpoint, that endpoint's disconnect handler (if set) is invoked. This handler is a simple base::OnceClosure
and may only be invoked once as long as the endpoint is bound to the same pipe. Typically clients and implementations use this handler to do some kind of cleanup or -- particuarly if the error was unexpected -- create a new pipe and attempt to establish a new connection with it.
All message pipe-binding C++ objects (e.g., mojo::Receiver<T>
, mojo::Remote<T>
, etc.) support setting their disconnect handler via a set_disconnect_handler
method.
We can set up another end-to-end Logger
example to demonstrate disconnect handler invocation. Suppose that LoggerImpl
had set up the following disconnect handler within its constructor:
LoggerImpl::LoggerImpl(mojo::PendingReceiver<sample::mojom::Logger> receiver) : receiver_(this, std::move(receiver)) { receiver_.set_disconnect_handler( base::BindOnce(&LoggerImpl::OnError, base::Unretained(this))); } void LoggerImpl::OnError() { LOG(ERROR) << "Client disconnected! Purging log lines."; lines_.clear(); } mojo::Remote<sample::mojom::Logger> logger; LoggerImpl impl(logger.BindNewPipeAndPassReceiver()); logger->Log("OK cool"); logger.reset(); // Closes the client end.
As long as impl
stays alive here, it will eventually receive the Log
message followed immediately by an invocation of the bound callback which outputs "Client disconnected! Purging log lines."
. Like all other receiver callbacks, a disconnect handler will never be invoked once its corresponding receiver object has been destroyed.
The use of base::Unretained
is safe because the error handler will never be invoked beyond the lifetime of receiver_
, and this
owns receiver_
.
Once a mojo::Remote<T>
is destroyed, it is guaranteed that pending callbacks as well as the connection error handler (if registered) won't be called.
Once a mojo::Receiver<T>
is destroyed, it is guaranteed that no more method calls are dispatched to the implementation and the connection error handler (if registered) won't be called.
A common situation when calling mojo interface methods that take a callback is that the caller wants to know if the other endpoint is torn down (e.g. because of a crash). In that case, the consumer usually wants to know if the response callback won't be run. There are different solutions for this problem, depending on how the Remote<T>
is held:
Remote<T>
: set_disconnect_handler
should be used.Remote<T>
: there are two helpers depending on the behavior that the caller wants. If the caller wants to ensure that an error handler is run, then mojo::WrapCallbackWithDropHandler
should be used. If the caller wants the callback to always be run, then mojo::WrapCallbackWithDefaultInvokeIfNotRun
helper should be used. With both of these helpers, usual callback care should be followed to ensure that the callbacks don’t run after the consumer is destructed (e.g. because the owner of the Remote<T>
outlives the consumer). This includes using base::WeakPtr
or base::RefCounted
. It should also be noted that with these helpers, the callbacks could be run synchronously while the Remote is reset or destroyed.As mentioned in the previous section, closing one end of a pipe will eventually trigger a connection error on the other end. However it's important to note that this event is itself ordered with respect to any other event (e.g. writing a message) on the pipe.
This means that it's safe to write something contrived like:
LoggerImpl::LoggerImpl(mojo::PendingReceiver<sample::mojom::Logger> receiver, base::OnceClosure disconnect_handler) : receiver_(this, std::move(receiver)) { receiver_.set_disconnect_handler(std::move(disconnect_handler)); } void GoBindALogger(mojo::PendingReceiver<sample::mojom::Logger> receiver) { base::RunLoop loop; LoggerImpl impl(std::move(receiver), loop.QuitClosure()); loop.Run(); } void LogSomething() { mojo::Remote<sample::mojom::Logger> logger; bg_thread->task_runner()->PostTask( FROM_HERE, base::BindOnce(&GoBindALogger, logger.BindNewPipeAndPassReceiver())); logger->Log("OK Computer"); }
When logger
goes out of scope it immediately closes its end of the message pipe, but the impl-side won't notice this until it receives the sent Log
message. Thus the impl
above will first log our message and then see a connection error and break out of the run loop.
Mojom enums translate directly to equivalent strongly-typed C++11 enum classes with int32_t
as the underlying type. The typename and value names are identical between Mojom and C++. Mojo also always defines a special enumerator kMaxValue
that shares the value of the highest enumerator: this makes it easy to record Mojo enums in histograms and interoperate with legacy IPC.
For example, consider the following Mojom definition:
module business.mojom; enum Department { kEngineering, kMarketing, kSales, };
This translates to the following C++ definition:
namespace business { namespace mojom { enum class Department : int32_t { kEngineering, kMarketing, kSales, kMaxValue = kSales, }; } // namespace mojom } // namespace business
Mojom structs can be used to define logical groupings of fields into a new composite type. Every Mojom struct elicits the generation of an identically named, representative C++ class, with identically named public fields of corresponding C++ types, and several helpful public methods.
For example, consider the following Mojom struct:
module business.mojom; struct Employee { int64 id; string username; Department department; };
This would generate a C++ class like so:
namespace business { namespace mojom { class Employee; using EmployeePtr = mojo::StructPtr<Employee>; class Employee { public: // Default constructor - applies default values, potentially ones specified // explicitly within the Mojom. Employee(); // Value constructor - an explicit argument for every field in the struct, in // lexical Mojom definition order. Employee(int64_t id, const std::string& username, Department department); // Creates a new copy of this struct value EmployeePtr Clone(); // Tests for equality with another struct value of the same type. bool Equals(const Employee& other); // Equivalent public fields with names identical to the Mojom. int64_t id; std::string username; Department department; }; } // namespace mojom } // namespace business
Note when used as a message parameter or as a field within another Mojom struct, a struct
type is wrapped by the move-only mojo::StructPtr
helper, which is roughly equivalent to a std::unique_ptr
with some additional utility methods. This allows struct values to be nullable and struct types to be potentially self-referential.
Every generated struct class has a static New()
method which returns a new mojo::StructPtr<T>
wrapping a new instance of the class constructed by forwarding the arguments from New
. For example:
mojom::EmployeePtr e1 = mojom::Employee::New(); e1->id = 42; e1->username = "mojo"; e1->department = mojom::Department::kEngineering;
is equivalent to
auto e1 = mojom::Employee::New(42, "mojo", mojom::Department::kEngineering);
Now if we define an interface like:
interface EmployeeManager { AddEmployee(Employee e); };
We'll get this C++ interface to implement:
class EmployeeManager { public: virtual ~EmployeManager() {} virtual void AddEmployee(EmployeePtr e) = 0; };
And we can send this message from C++ code as follows:
mojom::EmployeManagerPtr manager = ...; manager->AddEmployee( Employee::New(42, "mojo", mojom::Department::kEngineering)); // or auto e = Employee::New(42, "mojo", mojom::Department::kEngineering); manager->AddEmployee(std::move(e));
Similarly to structs, tagged unions generate an identically named, representative C++ class which is typically wrapped in a mojo::StructPtr<T>
.
Unlike structs, all generated union fields are private and must be retrieved and manipulated using accessors. A field foo
is accessible by get_foo()
and settable by set_foo()
. There is also a boolean is_foo()
for each field which indicates whether the union is currently taking on the value of field foo
in exclusion to all other union fields.
Finally, every generated union class also has a nested Tag
enum class which enumerates all of the named union fields. A Mojom union value's current type can be determined by calling the which()
method which returns a Tag
.
For example, consider the following Mojom definitions:
union Value { int64 int_value; float float_value; string string_value; }; interface Dictionary { AddValue(string key, Value value); };
This generates the following C++ interface:
class Value { public: ~Value() {} }; class Dictionary { public: virtual ~Dictionary() {} virtual void AddValue(const std::string& key, ValuePtr value) = 0; };
And we can use it like so:
ValuePtr value = Value::NewIntValue(42); CHECK(value->is_int_value()); CHECK_EQ(value->which(), Value::Tag::kIntValue); value->set_float_value(42); CHECK(value->is_float_value()); CHECK_EQ(value->which(), Value::Tag::kFloatValue); value->set_string_value("bananas"); CHECK(value->is_string_value()); CHECK_EQ(value->which(), Value::Tag::kStringValue);
Finally, note that if a union value is not currently occupied by a given field, attempts to access that field will DCHECK:
ValuePtr value = Value::NewIntValue(42); LOG(INFO) << "Value is " << value->get_string_value(); // DCHECK!
We know how to create interface pipes and use their Remote and PendingReceiver endpoints in some interesting ways. This still doesn‘t add up to interesting IPC! The bread and butter of Mojo IPC is the ability to transfer interface endpoints across other interfaces, so let’s take a look at how to accomplish that.
Consider a new example Mojom in //sample/db.mojom
:
module db.mojom; interface Table { void AddRow(int32 key, string data); }; interface Database { AddTable(pending_receiver<Table> table); };
As noted in the Mojom IDL documentation, the pending_receiver<Table>
syntax corresponds precisely to the PendingReceiver<T>
type discussed in the sections above, and in fact the generated code for these interfaces is approximately:
namespace db { namespace mojom { class Table { public: virtual ~Table() {} virtual void AddRow(int32_t key, const std::string& data) = 0; } class Database { public: virtual ~Database() {} virtual void AddTable(mojo::PendingReceiver<Table> table); }; } // namespace mojom } // namespace db
We can put this all together now with an implementation of Table
and Database
:
#include "sample/db.mojom.h" class TableImpl : public db::mojom:Table { public: explicit TableImpl(mojo::PendingReceiver<db::mojom::Table> receiver) : receiver_(this, std::move(receiver)) {} ~TableImpl() override {} // db::mojom::Table: void AddRow(int32_t key, const std::string& data) override { rows_.insert({key, data}); } private: mojo::Receiver<db::mojom::Table> receiver_; std::map<int32_t, std::string> rows_; }; class DatabaseImpl : public db::mojom::Database { public: explicit DatabaseImpl(mojo::PendingReceiver<db::mojom::Database> receiver) : receiver_(this, std::move(receiver)) {} ~DatabaseImpl() override {} // db::mojom::Database: void AddTable(mojo::PendingReceiver<db::mojom::Table> table) { tables_.emplace_back(std::make_unique<TableImpl>(std::move(table))); } private: mojo::Receiver<db::mojom::Database> receiver_; std::vector<std::unique_ptr<TableImpl>> tables_; };
Pretty straightforward. The pending_receiver<Table>
Mojom parameter to AddTable
translates to a C++ mojo::PendingReceiver<db::mojom::Table>
, which we know is just a strongly-typed message pipe handle. When DatabaseImpl
gets an AddTable
call, it constructs a new TableImpl
and binds it to the received mojo::PendingReceiver<db::mojom::Table>
.
Let's see how this can be used.
mojo::Remote<db::mojom::Database> database; DatabaseImpl db_impl(database.BindNewPipeAndPassReceiver()); mojo::Remote<db::mojom::Table> table1, table2; database->AddTable(table1.BindNewPipeAndPassReceiver()); database->AddTable(table2.BindNewPipeAndPassReceiver()); table1->AddRow(1, "hiiiiiiii"); table2->AddRow(2, "heyyyyyy");
Notice that we can again start using the new Table
pipes immediately, even while their mojo::PendingReceiver<db::mojom::Table>
endpoints are still in transit.
Of course we can also send Remote
s:
interface TableListener { OnRowAdded(int32 key, string data); }; interface Table { AddRow(int32 key, string data); AddListener(pending_remote<TableListener> listener); };
This would generate a Table::AddListener
signature like so:
virtual void AddListener(mojo::PendingRemote<TableListener> listener) = 0;
and this could be used like so:
mojo::PendingRemote<db::mojom::TableListener> listener; TableListenerImpl impl(listener.InitWithNewPipeAndPassReceiver()); table->AddListener(std::move(listener));
The Interfaces section above covers basic usage of the most common bindings object types: Remote
, PendingReceiver
, and Receiver
. While these types are probably the most commonly used in practice, there are several other ways of binding both client- and implementation-side interface pipes.
A self-owned receiver exists as a standalone object which owns its interface implementation and automatically cleans itself up when its bound interface endpoint detects an error. The MakeSelfOwnedReceiver
function is used to create such a receiver. .
class LoggerImpl : public sample::mojom::Logger { public: LoggerImpl() {} ~LoggerImpl() override {} // sample::mojom::Logger: void Log(const std::string& message) override { LOG(ERROR) << "[Logger] " << message; } private: // NOTE: This doesn't own any Receiver object! }; mojo::Remote<db::mojom::Logger> logger; mojo::MakeSelfOwnedReceiver(std::make_unique<LoggerImpl>(), logger.BindNewPipeAndPassReceiver()); logger->Log("NOM NOM NOM MESSAGES");
Now as long as logger
remains open somewhere in the system, the bound LoggerImpl
on the other end will remain alive.
Sometimes it's useful to share a single implementation instance with multiple clients. ReceiverSet
makes this easy. Consider the Mojom:
module system.mojom; interface Logger { Log(string message); }; interface LoggerProvider { GetLogger(Logger& logger); };
We can use ReceiverSet
to bind multiple Logger
pending receivers to a single implementation instance:
class LogManager : public system::mojom::LoggerProvider, public system::mojom::Logger { public: explicit LogManager(mojo::PendingReceiver<system::mojom::LoggerProvider> receiver) : provider_receiver_(this, std::move(receiver)) {} ~LogManager() {} // system::mojom::LoggerProvider: void GetLogger(mojo::PendingReceiver<Logger> receiver) override { logger_receivers_.Add(this, std::move(receiver)); } // system::mojom::Logger: void Log(const std::string& message) override { LOG(ERROR) << "[Logger] " << message; } private: mojo::Receiver<system::mojom::LoggerProvider> provider_receiver_; mojo::ReceiverSet<system::mojom::Logger> logger_receivers_; };
Similar to the ReceiverSet
above, sometimes it's useful to maintain a set of Remote
s for e.g. a set of clients observing some event. RemoteSet
is here to help. Take the Mojom:
module db.mojom; interface TableListener { OnRowAdded(int32 key, string data); }; interface Table { AddRow(int32 key, string data); AddListener(pending_remote<TableListener> listener); };
An implementation of Table
might look something like like this:
class TableImpl : public db::mojom::Table { public: TableImpl() {} ~TableImpl() override {} // db::mojom::Table: void AddRow(int32_t key, const std::string& data) override { rows_.insert({key, data}); for (auto& listener : listeners_) { listener->OnRowAdded(key, data); } } void AddListener(mojo::PendingRemote<db::mojom::TableListener> listener) { listeners_.Add(std::move(listener)); } private: mojo::RemoteSet<db::mojom::Table> listeners_; std::map<int32_t, std::string> rows_; };
Associated interfaces are interfaces which:
New types pending_associated_remote
and pending_associated_receiver
are introduced for remote/receiver fields. For example:
interface Bar {}; struct Qux { pending_associated_remote<Bar> bar; }; interface Foo { // Uses associated remote. PassBarRemote(pending_associated_remote<Bar> bar); // Uses associated receiver. PassBarReceiver(pending_associated_receiver<Bar> bar); // Passes a struct with associated interface pointer. PassQux(Qux qux); // Uses associated interface pointer in callback. AsyncGetBar() => (pending_associated_remote<Bar> bar); };
In each case the interface impl/client will communicate using the same message pipe over which the associated remote/receiver is passed.
When generating C++ bindings, the pending_associated_remote of Bar
is mapped to mojo::PendingAssociatedRemote<Bar>
; pending_associated_receiver to mojo::PendingAssociatedReceiver<Bar>
.
// In mojom: interface Foo { ... PassBarRemote(pending_associated_remote<Bar> bar); PassBarReceiver(pending_associated_receiver<Bar> bar); ... }; // In C++: class Foo { ... virtual void PassBarRemote(mojo::PendingAssociatedRemote<Bar> bar) = 0; virtual void PassBarReceiver(mojo::PendingAssociatedReceiver<Bar> bar) = 0; ... };
Assume you already have a Remote<Foo> foo
, and you would like to call PassBarReceiver()
on it. You can do:
mojo::PendingAssociatedRemote<Bar> pending_bar; mojo::PendingAssociatedReceiver<Bar> bar_receiver = pending_bar.InitWithNewEndpointAndPassReceiver(); foo->PassBarReceiver(std::move(bar_receiver)); mojo::AssociatedRemote<Bar> bar; bar.Bind(std::move(pending_bar)); bar->DoSomething();
First, the code creates an associated interface of type Bar
. It looks very similar to what you would do to setup a non-associated interface. An important difference is that one of the two associated endpoints (either bar_receiver
or pending_bar
) must be sent over another interface. That is how the interface is associated with an existing message pipe.
It should be noted that you cannot call bar->DoSomething()
before passing bar_receiver
. This is required by the FIFO-ness guarantee: at the receiver side, when the message of DoSomething
call arrives, we want to dispatch it to the corresponding AssociatedReceiver<Bar>
before processing any subsequent messages. If bar_receiver
is in a subsequent message, message dispatching gets into a deadlock. On the other hand, as soon as bar_receiver
is sent, bar
is usable. There is no need to wait until bar_receiver
is bound to an implementation at the remote side.
AssociatedRemote
provides a BindNewEndpointAndPassReceiver
method to make the code a little shorter. The following code achieves the same purpose:
mojo::AssociatedRemote<Bar> bar; foo->PassBarReceiver(bar.BindNewEndpointAndPassReceiver()); bar->DoSomething();
The implementation of Foo
looks like this:
class FooImpl : public Foo { ... void PassBarReceiver(mojo::AssociatedReceiver<Bar> bar) override { bar_receiver_.Bind(std::move(bar)); ... } ... Receiver<Foo> foo_receiver_; AssociatedReceiver<Bar> bar_receiver_; };
In this example, bar_receiver_
‘s lifespan is tied to that of FooImpl
. But you don’t have to do that. You can, for example, pass bar2
to another sequence to bind to an AssociatedReceiver<Bar>
there.
When the underlying message pipe is disconnected (e.g., foo
or foo_receiver_
is destroyed), all associated interface endpoints (e.g., bar
and bar_receiver_
) will receive a disconnect error.
Similarly, assume you have already got an Remote<Foo> foo
, and you would like to call PassBarRemote()
on it. You can do:
mojo::AssociatedReceiver<Bar> bar_receiver(some_bar_impl); mojo::PendingAssociatedRemote<Bar> bar; mojo::PendingAssociatedReceiver<Bar> bar_pending_receiver = bar.InitWithNewEndpointAndPassReceiver(); foo->PassBarRemote(std::move(bar)); bar_receiver.Bind(std::move(bar_pending_receiver));
The following code achieves the same purpose:
mojo::AssociatedReceiver<Bar> bar_receiver(some_bar_impl); mojo::PendingAssociatedRemote<Bar> bar; bar_receiver.Bind(bar.InitWithNewPipeAndPassReceiver()); foo->PassBarRemote(std::move(bar));
When using associated interfaces on different sequences than the primary sequence (where the primary interface lives):
Therefore, performance-wise associated interfaces are better suited for scenarios where message receiving happens on the primary sequence.
Associated interfaces need to be associated with a primary interface before they can be used. This means one end of the associated interface must be sent over one end of the primary interface, or over one end of another associated interface which itself already has a primary interface.
If you want to test an associated interface endpoint without first associating it, you can use AssociatedRemote::BindNewEndpointAndPassDedicatedReceiver
. This will create working associated interface endpoints which are not actually associated with anything else.
Although sync calls are convenient, you should avoid them whenever they are not absolutely necessary:
A new attribute [Sync]
(or [Sync=true]
) is introduced for methods. For example:
interface Foo { [Sync] SomeSyncCall() => (Bar result); };
It indicates that when SomeSyncCall()
is called, the control flow of the calling thread is blocked until the response is received.
It is not allowed to use this attribute with functions that don’t have responses. If you just need to wait until the service side finishes processing the call, you can use an empty response parameter list:
[Sync] SomeSyncCallWithNoResult() => ();
The generated C++ interface of the Foo interface above is:
class Foo { public: // The service side implements this signature. The client side can // also use this signature if it wants to call the method asynchronously. virtual void SomeSyncCall(SomeSyncCallCallback callback) = 0; // The client side uses this signature to call the method synchronously. virtual bool SomeSyncCall(BarPtr* result); };
As you can see, the client side and the service side use different signatures. At the client side, response is mapped to output parameters and the boolean return value indicates whether the operation is successful. (Returning false usually means a connection error has occurred.)
At the service side, a signature with callback is used. The reason is that in some cases the implementation may need to do some asynchronous work which the sync method’s result depends on.
What happens on the calling thread while waiting for the response of a sync method call? It continues to process incoming sync request messages (i.e., sync method calls); block other messages, including async messages and sync response messages that don’t match the ongoing sync call.
Please note that sync response messages that don’t match the ongoing sync call cannot re-enter. That is because they correspond to sync calls down in the call stack. Therefore, they need to be queued and processed while the stack unwinds.
Please note that the re-entrancy behavior doesn’t prevent deadlocks involving async calls. You need to avoid call sequences such as:
In many instances you might prefer that your generated C++ bindings use a more natural type to represent certain Mojom types in your interface methods. For one example consider a Mojom struct such as the Rect
below:
module gfx.mojom; struct Rect { int32 x; int32 y; int32 width; int32 height; }; interface Canvas { void FillRect(Rect rect); };
The Canvas
Mojom interface would normally generate a C++ interface like:
class Canvas { public: virtual void FillRect(RectPtr rect) = 0; };
However, the Chromium tree already defines a native gfx::Rect
which is equivalent in meaning but which also has useful helper methods. Instead of manually converting between a gfx::Rect
and the Mojom-generated RectPtr
at every message boundary, wouldn't it be nice if the Mojom bindings generator could instead generate:
class Canvas { public: virtual void FillRect(const gfx::Rect& rect) = 0; }
The correct answer is, “Yes! That would be nice!” And fortunately, it can!
StructTraits
In order to teach generated bindings code how to serialize an arbitrary native type T
as an arbitrary Mojom type mojom::U
, we need to define an appropriate specialization of the mojo::StructTraits
template.
A valid specialization of StructTraits
MUST define the following static methods:
A single static accessor for every field of the Mojom struct, with the exact same name as the struct field. These accessors must all take a (preferably const) ref to an object of the native type, and must return a value compatible with the Mojom struct field's type. This is used to safely and consistently extract data from the native type during message serialization without incurring extra copying costs.
A single static Read
method which initializes an instance of the the native type given a serialized representation of the Mojom struct. The Read
method must return a bool
to indicate whether the incoming data is accepted (true
) or rejected (false
).
In order to define the mapping for gfx::Rect
, we want the following StructTraits
specialization, which we'll define in //ui/gfx/geometry/mojo/geometry_mojom_traits.h
:
#include "mojo/public/cpp/bindings/mojom_traits.h" #include "ui/gfx/geometry/rect.h" #include "ui/gfx/geometry/mojo/geometry.mojom.h" namespace mojo { template <> class StructTraits<gfx::mojom::RectDataView, gfx::Rect> { public: static int32_t x(const gfx::Rect& r) { return r.x(); } static int32_t y(const gfx::Rect& r) { return r.y(); } static int32_t width(const gfx::Rect& r) { return r.width(); } static int32_t height(const gfx::Rect& r) { return r.height(); } static bool Read(gfx::mojom::RectDataView data, gfx::Rect* out_rect); }; } // namespace mojo
And in //ui/gfx/geometry/mojo/geometry_mojom_traits.cc
:
#include "ui/gfx/geometry/mojo/geometry_mojom_traits.h" namespace mojo { // static bool StructTraits<gfx::mojom::RectDataView, gfx::Rect>::Read( gfx::mojom::RectDataView data, gfx::Rect* out_rect) { if (data.width() < 0 || data.height() < 0) return false; out_rect->SetRect(data.x(), data.y(), data.width(), data.height()); return true; }; } // namespace mojo
Note that the Read()
method returns false
if either the incoming width
or height
fields are negative. This acts as a validation step during deserialization: if a client sends a gfx::Rect
with a negative width or height, its message will be rejected and the pipe will be closed. In this way, type mapping can serve to enable custom validation logic in addition to making callsites and interface implemention more convenient.
When the struct fields have non-primitive types, e.g. string or array, returning a read-only view of the data in the accessor is recommended to avoid copying. It is safe because the input object is guaranteed to outlive the usage of the result returned by the accessor method.
The following example uses StringPiece
to return a view of the GURL's data (//url/mojom/url_gurl_mojom_traits.h
):
#include "base/strings/string_piece.h" #include "url/gurl.h" #include "url/mojom/url.mojom.h" #include "url/url_constants.h" namespace mojo { template <> struct StructTraits<url::mojom::UrlDataView, GURL> { static base::StringPiece url(const GURL& r) { if (r.possibly_invalid_spec().length() > url::kMaxURLChars || !r.is_valid()) { return base::StringPiece(); } return base::StringPiece(r.possibly_invalid_spec().c_str(), r.possibly_invalid_spec().length()); } } // namespace mojo
We've defined the StructTraits
necessary, but we still need to teach the bindings generator (and hence the build system) about the mapping. To do this we must add some more information to our mojom
target in GN:
# Without a typemap mojom("mojom") { sources = [ "rect.mojom", ] } # With a typemap. mojom("mojom") { sources = [ "rect.mojom", ] cpp_typemaps = [ { # NOTE: A single typemap entry can list multiple individual type mappings. # Each mapping assumes the same values for |traits_headers| etc below. # # To typemap a type with separate |traits_headers| etc, add a separate # entry to |cpp_typemaps|. types = [ { mojom = "gfx.mojom.Rect" cpp = "::gfx::Rect" }, ] traits_headers = [ "//ui/gfx/geometry/mojo/geometry_mojom_traits.h" ] traits_sources = [ "//ui/gfx/geometry/mojo/geometry_mojom_traits.cc" ] traits_public_deps = [ "//ui/gfx/geometry" ] }, ] }
See typemap documentation in mojom.gni for details on the above definition and other supported parameters.
With this extra configuration present, any mojom references to gfx.mojom.Rect
(e.g. for method parameters or struct fields) will be gfx::Rect
references in generated C++ code.
For the Blink variant of bindings, add to the blink_cpp_typemaps
list instead.
traits_sources
Using traits_sources
in a typemap configuration means that the listed sources will be baked directly into the corresponding mojom
target's own sources. This can be problematic if you want to use the same typemap for both Blink and non-Blink bindings.
For such cases, it is recommended that you define a separate component
target for your typemap traits, and reference this in the traits_public_deps
of the typemap:
mojom("mojom") { sources = [ "rect.mojom", ] cpp_typemaps = [ { types = [ { mojom = "gfx.mojom.Rect" cpp = "::gfx::Rect" }, ] traits_headers = [ "//ui/gfx/geometry/mojo/geometry_mojom_traits.h" ] traits_public_deps = [ ":geometry_mojom_traits" ] }, ] } component("geometry_mojom_traits") { sources = [ "//ui/gfx/geometry/mojo/geometry_mojom_traits.cc", "//ui/gfx/geometry/mojo/geometry_mojom_traits.h", ] # The header of course needs corresponding COMPONENT_EXPORT() tags. defines = [ "IS_GEOMETRY_MOJOM_TRAITS_IMPL" ] }
Each of a StructTraits
specialization's static getter methods -- one per struct field -- must return a type which can be used as a data source for the field during serialization. This is a quick reference mapping Mojom field type to valid getter return types:
Mojom Field Type | C++ Getter Return Type |
---|---|
bool | bool |
int8 | int8_t |
uint8 | uint8_t |
int16 | int16_t |
uint16 | uint16_t |
int32 | int32_t |
uint32 | uint32_t |
int64 | int64_t |
uint64 | uint64_t |
float | float |
double | double |
handle | mojo::ScopedHandle |
handle<message_pipe> | mojo::ScopedMessagePipeHandle |
handle<data_pipe_consumer> | mojo::ScopedDataPipeConsumerHandle |
handle<data_pipe_producer> | mojo::ScopedDataPipeProducerHandle |
handle<platform> | mojo::PlatformHandle |
handle<shared_buffer> | mojo::ScopedSharedBufferHandle |
pending_remote<Foo> | mojo::PendingRemote<Foo> |
pending_receiver<Foo> | mojo::PendingReceiver<Foo> |
pending_associated_remote<Foo> | mojo::PendingAssociatedRemote<Foo> |
pending_associated_receiver<Foo> | mojo::PendingAssociatedReceiver<Foo> |
string | Value or reference to any type T that has a mojo::StringTraits specialization defined. By default this includes std::string , base::StringPiece , and WTF::String (Blink). |
array<T> | Value or reference to any type T that has a mojo::ArrayTraits specialization defined. By default this includes std::array<T, N> , std::vector<T> , WTF::Vector<T> (Blink), etc. |
array<T, N> | Similar to the above, but the length of the data must be always the same as N . |
map<K, V> | Value or reference to any type T that has a mojo::MapTraits specialization defined. By default this includes std::map<T> , mojo::unordered_map<T> , WTF::HashMap<T> (Blink), etc. |
FooEnum | Value of any type that has an appropriate EnumTraits specialization defined. By default this includes only the generated FooEnum type. |
FooStruct | Value or reference to any type that has an appropriate StructTraits specialization defined. By default this includes only the generated FooStructPtr type. |
FooUnion | Value of reference to any type that has an appropriate UnionTraits specialization defined. By default this includes only the generated FooUnionPtr type. |
Foo? | absl::optional<CppType> , where CppType is the value type defined by the appropriate traits class specialization (e.g. StructTraits , mojo::MapTraits , etc.). This may be customized by the typemapping. |
Static Read
methods on StructTraits
specializations get a generated FooDataView
argument (such as the RectDataView
in the example above) which exposes a direct view of the serialized Mojom structure within an incoming message's contents. In order to make this as easy to work with as possible, the generated FooDataView
types have a generated method corresponding to every struct field:
For POD field types (e.g. bools, floats, integers) these are simple accessor methods with names identical to the field name. Hence in the Rect
example we can access things like data.x()
and data.width()
. The return types correspond exactly to the mappings listed in the table above, under StructTraits Reference.
For handle and interface types (e.g handle
or pending_remote<Foo>
) these are named TakeFieldName
(for a field named field_name
) and they return an appropriate move-only handle type by value. The return types correspond exactly to the mappings listed in the table above, under StructTraits Reference.
For all other field types (e.g., enums, strings, arrays, maps, structs) these are named ReadFieldName
(for a field named field_name
) and they return a bool
(to indicate success or failure in reading). On success they fill their output argument with the deserialized field value. The output argument may be a pointer to any type with an appropriate StructTraits
specialization defined, as mentioned in the table above, under StructTraits Reference.
An example would be useful here. Suppose we introduced a new Mojom struct:
struct RectPair { Rect left; Rect right; };
and a corresponding C++ type:
class RectPair { public: RectPair() {} const gfx::Rect& left() const { return left_; } const gfx::Rect& right() const { return right_; } void Set(const gfx::Rect& left, const gfx::Rect& right) { left_ = left; right_ = right; } // ... some other stuff private: gfx::Rect left_; gfx::Rect right_; };
Our traits to map gfx::mojom::RectPair
to gfx::RectPair
might look like this:
namespace mojo { template <> class StructTraits public: static const gfx::Rect& left(const gfx::RectPair& pair) { return pair.left(); } static const gfx::Rect& right(const gfx::RectPair& pair) { return pair.right(); } static bool Read(gfx::mojom::RectPairDataView data, gfx::RectPair* out_pair) { gfx::Rect left, right; if (!data.ReadLeft(&left) || !data.ReadRight(&right)) return false; out_pair->Set(left, right); return true; } } // namespace mojo
Generated ReadFoo
methods always convert multi_word_field_name
fields to ReadMultiWordFieldName
methods.
By now you may have noticed that additional C++ sources are generated when a Mojom is processed. These exist due to type mapping, and the source files we refer to throughout this docuemnt (namely foo.mojom.cc
and foo.mojom.h
) are really only one variant (the default or chromium variant) of the C++ bindings for a given Mojom file.
The only other variant currently defined in the tree is the blink variant, which produces a few additional files:
out/gen/sample/db.mojom-blink.cc out/gen/sample/db.mojom-blink.h
These files mirror the definitions in the default variant but with different C++ types in place of certain builtin field and parameter types. For example, Mojom strings are represented by WTF::String
instead of std::string
. To avoid symbol collisions, the variant's symbols are nested in an extra inner namespace, so Blink consumer of the interface might write something like:
#include "sample/db.mojom-blink.h" class TableImpl : public db::mojom::blink::Table { public: void AddRow(int32_t key, const WTF::String& data) override { // ... } };
In addition to using different C++ types for builtin strings, arrays, and maps, the custom typemaps applied to Blink bindings are managed separately from regular bindings.
mojom
targets support a blink_cpp_typemaps
parameter in addition to the regular cpp_typemaps
. This lists the typemaps to apply to Blink bindings.
To depend specifically on generated Blink bindings, reference ${target_name}_blink
. So for example, with the definition:
# In //foo/mojom mojom("mojom") { sources = [ "db.mojom", ] }
C++ sources can depend on the Blink bindings by depending on "//foo/mojom:mojom_blink"
.
Finally note that both bindings variants share some common definitions which are unaffected by differences in the type-mapping configuration (like enums, and structures describing serialized object formats). These definitions are generated in shared sources:
out/gen/sample/db.mojom-shared.cc out/gen/sample/db.mojom-shared.h out/gen/sample/db.mojom-shared-internal.h
Including either variant's header (db.mojom.h
or db.mojom-blink.h
) implicitly includes the shared header, but may wish to include only the shared header in some instances.
C++ sources can depend on shared sources only, by referencing the "${target_name}_shared"
target, e.g. "//foo/mojom:mojom_shared"
in the example above.
For converting between Blink and non-Blink variants, please see //third_party/blink/public/platform/cross_variant_mojo_util.h
.
For general documentation of versioning in the Mojom IDL see Versioning.
This section briefly discusses some C++-specific considerations relevant to versioned Mojom types.
Remote
defines the following methods to query or assert remote interface version:
void QueryVersion(base::OnceCallback<void(uint32_t)> callback);
This queries the remote endpoint for the version number of its binding. When a response is received callback
is invoked with the remote version number. Note that this value is cached by the Remote
instance to avoid redundant queries.
void RequireVersion(uint32_t version);
Informs the remote endpoint that a minimum version of version
is required by the client. If the remote endpoint cannot support that version, it will close its end of the pipe immediately, preventing any other requests from being received.
All extensible enums should have one enumerator value designated as the default using the [Default]
attribute. When Mojo deserializes an enum value that is not defined in the current version of the enum definition, that value will be transparently mapped to the [Default]
enumerator value. Implementations can use the presence of this enumerator value to correctly handle version skew.
[Extensible] enum Department { [Default] kUnknown, kSales, kDev, kResearch, };
See Converting Legacy Chrome IPC To Mojo.
Calling Mojo From Blink: A brief overview of what it looks like to use Mojom C++ bindings from within Blink code.