mojo/docs/basics.md

   1 # Mojo Basics
   2
   3 This document aims to provide a brief overview of the different concepts in Mojo
   4 and how they work together.  For more details about more complex and/or
   5 Chrome-specific Mojo use cases, please consult [Intro to Mojo & Services](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/mojo_and_services.md).
   6
   7 [TOC]
   8
   9 ## Interfaces
  10
  11 Mojo provides a [C++-like interface definition language][mojo-idl] for defining
  12 interfaces for making interprocess calls (IPCs):
  13
  14 ```
  15 module math.mojom;
  16
  17 interface Math {
  18   // Adds two int32s and returns the result as an int64 (to avoid
  19   // overflow issues).
  20   Add(int32 x, int32 y) => (int64 sum);
  21 };
  22 ```
  23
  24 Interfaces are built using the `mojom` (or `mojom_component`) [GN
  25 template][gn-template]:
  26 ```
  27 mojom("mojom") {
  28   sources = ["math.mojom"]
  29 }
  30 ```
  31
  32 This will generate C++ (and optionally, Java and JavaScript) interfaces. Writing
  33 code to handle IPCs is a simple matter of implementing the generated interface:
  34
  35 ```c++
  36 class MathImpl : public math::mojom::Math {
  37  public:
  38   explicit MathImpl(mojo::PendingReceiver<math::mojom::Math> receiver)
  39       : receiver_(this, std::move(receiver)) {}
  40
  41   // math::mojom::Math overrides:
  42   // Note: AddCallback is a type alias for base::OnceCallback<void(int64_t)>.
  43   // The parameters to the callback are the reply parameters specified in the
  44   // Mojo IDL method definition. This is part of the boilerplate generated by
  45   // Mojo: invoking |reply| will send a reply to the caller.
  46   void Add(int32_t x, int32_t y, AddCallback reply) override {
  47     // Note: Mojo always returns results via callback. While it is possible to
  48     // make a sync IPC which blocks on the reply, the handler will always return
  49     // the result via callback.
  50     std::move(reply).Run(static_cast<int64_t>(x) + y);
  51   }
  52
  53  private:
  54   // Wraps a message pipe endpoint that receives incoming messages. See the
  55   // message pipes section below for more information.
  56   mojo::Receiver<math::mojom::Math> receiver_;
  57 };
  58 ```
  59
  60 Note: the build process also generates proxy classes (e.g. `MathProxy`) which
  61 encapsulate the details of making the actual cross-process call. These are
  62 used internally and are an implementation detail that can typically be ignored.
  63
  64 ## Message Pipes
  65
  66 Interfaces are layered on top of low-level [message pipes][message-pipe]. Each
  67 message pipe has two bidirectional endpoints. The Mojo bindings enforce
  68 additional conventions on top of message pipes, where one endpoint is the
  69 sender/caller, represented as:
  70
  71 ```c++
  72 // Wraps a message pipe endpoint for making remote calls. May only be used on
  73 // the sequence where the mojo::Remote was bound.
  74 mojo::Remote<math::mojom::Math> remote_math = ...;
  75 ```
  76
  77 And the other endpoint is the receiving/callee, represented as:
  78
  79 ```c++
  80 // Usually a class member. Wraps a message pipe endpoint that receives incoming
  81 // messages. Routes and dispatches IPCs to the handler—typically |this|—on the
  82 // sequence where the mojo::Receiver was bound.
  83 mojo::Receiver<math::mojom::Math> receiver_;
  84 ```
  85
  86 This allows limited bidirectional communication. For one interface, the sender
  87 (A) may make any number of calls to the receiver (B). (B) may send a single
  88 reply for each call from (A). More expressive APIs are often implemented as a
  89 pair of interfaces (with two underlying message pipes), allowing calls to be
  90 made in either direction between (A) and (B).
  91
  92 Message pipe endpoints are typically created using one of:
  93
  94 ### mojo::Remote<T>::BindNewPipeAndPassReceiver
  95
  96 Used when the sender/caller creates the endpoints. One endpoint is retained for
  97 itself to send IPCs, and the other endpoint is returned as an unbound
  98 `mojo::PendingReceiver<T>` for the receiver/callee to bind to a
  99 `mojo::Receiver<T>`.
 100
 101 ```c++
 102 mojo::Remote<math::mojom::Math> remote_math;
 103
 104 // BindNewPipeAndPassReceiver() returns a
 105 // mojo::PendingReceiver<math::mojom::Math>. This may be bound to a
 106 // mojo::Receiver<math::mojom::Math> to handle calls received from
 107 // |remote_math|.
 108 LaunchAndBindRemoteMath(remote_math.BindNewPipeAndPassReceiver());
 109
 110 // |remote_math| may be immediately used. The Add() call will be buffered by the
 111 // receiving end and dispatched when mojo::PendingReceiver<math::mojom::Math> is
 112 // bound to a mojo::Receiver<math::mojom::Math>.
 113 remote_math->Add(2, 2, base::BindOnce(...));
 114 ```
 115
 116 ### mojo::Receiver<T>::BindNewPipeAndPassRemote
 117
 118 Used when the receiver/callee creates the endpoints. One endpoint is retained
 119 for itself to receive IPCs, and the other endpoint is returned as an unbound
 120 `mojo::PendingRemote<T>` for the sender/callee to bind to a `mojo::Remote<T>`.
 121
 122 ```c++
 123 class MathImpl : public math::mojom::MathImpl {
 124   // ...addition to the previous MathImpl definition...
 125
 126   mojo::PendingRemote<math::mojom::Math> GetRemoteMath() {
 127     // BindNewPipeAndPassRemote() returns a
 128     // `mojo::PendingRemote<math::mojom::Math>`. This may be bound to a
 129     // `mojo::Remote<math::mojom::Math> which can be used to send IPCs that will
 130     // be handled by |this|.
 131     return receiver_.BindNewPipeAndPassRemote();
 132   }
 133 };
 134 ```
 135
 136 ### mojo::PendingRemote<T>::InitWithNewPipeAndPassReceiver
 137
 138 Less common, but similar to `mojo::Remote<T>::BindNewPipeAndPassReceiver()`.
 139 Typically used by broker code that needs to hand off a `mojo::PendingRemote<T>`
 140 to the sender/caller side and hand off a `mojo::PendingReceiver<T>` to the
 141 receiver/callee side.
 142
 143 ### mojo::Remote<T>/mojo::Receiver<T> and mojo::PendingRemote<T>/mojo::PendingReceiver<T>
 144
 145 Both `mojo::Remote<T>` and `mojo::Receiver<T>` have a corresponding unbound
 146 version: this allows either endpoint to be passed between sequences in the same
 147 process or even between processes over IPC.
 148
 149 ```c++
 150 mojo::Remote<math::mojom::MathImpl> remote = ...;
 151 // |pending_remote| is movable and may be passed around. While unbound, the
 152 // endpoint cannot be used to send IPCs. The pending remote may be passed to
 153 // the mojo::Remote<T> constructor or mojo::Remote<T>::Bind() to rebind the
 154 // endpoint.
 155 mojo::PendingRemote<math::mojom::MathImpl> pending_remote = remote.Unbind();
 156 ```
 157
 158 ```c++
 159 mojo::Receiver<math::mojom::MathImpl> receiver = ...;
 160 // |pending_receiver| is movable and may be passed around. While unbound,
 161 // received IPCs are buffered and not processed. The pending receiver may be
 162 // passed to the mojo::Receiver<T> constructor or mojo::Receiver<T>::Bind() to
 163 // rebind the endpoint.
 164 mojo::PendingReceiver<math::mojom::MathImpl> pending_receiver = receiver.Unbind();
 165 ```
 166
 167 [mojo-idl]: https://chromium.googlesource.com/chromium/src/+/master/mojo/public/tools/bindings/README.md
 168 [gn-template]: https://cs.chromium.org/chromium/src/mojo/public/tools/bindings/mojom.gni
 169 [message-pipe]: https://cs.chromium.org/chromium/src/mojo/public/cpp/system/message_pipe.h