mojo/README.md

   1 # Mojo
   2
   3 [TOC]
   4
   5 ## Getting Started With Mojo
   6
   7 To get started using Mojo in Chromium, the fastest path forward will likely be
   8 to read the Mojo sections of the
   9 [Intro to Mojo &amp; Services](/docs/mojo_and_services.md) guide.
  10
  11 For more detailed reference material on the most commonly used features of Mojo,
  12 head directly to the [bindings](#Bindings-APIs) documentation for your language
  13 of choice or the more general
  14 [mojom Interface Definition Language (IDL)](/mojo/public/tools/bindings/README.md)
  15 documentation.
  16
  17 If you're looking for information on creating and/or connecting to services,
  18 you're in the wrong place! Mojo does not deal with services, it only facilitates
  19 interface definition, message passing, and other lower-level IPC primitives.
  20 Instead, you should take a look at some of the other available
  21 [Mojo &amp; Services](/docs/README.md#Mojo-Services) documentation.
  22
  23 ## System Overview
  24
  25 Mojo is a collection of runtime libraries providing a platform-agnostic
  26 abstraction of common IPC primitives, a message IDL format, and a bindings
  27 library with code generation for multiple target languages to facilitate
  28 convenient message passing across arbitrary inter- and intra-process boundaries.
  29
  30 The documentation here is segmented according to the different libraries
  31 comprising Mojo. Mojo is divided into cleanly-separated layers with the basic
  32 hierarchy of subcomponents as follows:
  33
  34 ![Mojo Library Layering: Core on bottom, language bindings on top, public system support APIs in the middle](/docs/images/mojo_stack.png)
  35
  36 ## Mojo Core
  37 In order to use any of the more interesting high-level support libraries like
  38 the System APIs or Bindings APIs, a process must first initialize Mojo Core.
  39 This is a one-time initialization which remains active for the remainder of the
  40 process's lifetime. There are two ways to initialize Mojo Core: via the Embedder
  41 API, or through a dynamically linked library.
  42
  43 ### Embedding
  44 Many processes to be interconnected via Mojo are **embedders**, meaning that
  45 they statically link against the `//mojo/core/embedder` target and initialize
  46 Mojo support within each process by calling `mojo::core::Init()`. See
  47 [**Mojo Core Embedder API**](/mojo/core/embedder/README.md) for more details.
  48
  49 This is a reasonable option when you can guarantee that all interconnected
  50 process binaries are linking against precisely the same revision of Mojo Core.
  51 This includes Chromium itself as well as any developer tools and test
  52 executables built within the tree.
  53
  54 To support other scenarios, use dynamic linking.
  55
  56 ### Dynamic Linking
  57 On some platforms, it's also possible for applications to rely on a
  58 dynamically-linked Mojo Core library (`libmojo_core.so` or `mojo_core.dll`)
  59 instead of statically linking against Mojo Core.
  60
  61 In order to take advantage of this mechanism, the library's binary must be
  62 present in either:
  63
  64   - The working directory of the application
  65   - A directory named by the `MOJO_CORE_LIBRARY_PATH` environment variable
  66   - A directory named explicitly by the application at runtime
  67
  68 Instead of calling `mojo::core::Init()` as embedders do, an application using
  69 dynamic Mojo Core instead calls `MojoInitialize()` from the C System API. This
  70 call will attempt to locate (see above) and load the Mojo Core library to
  71 support subsequent Mojo API usage within the process.
  72
  73 Note that the Mojo Core shared library presents a **stable C ABI** designed with
  74 both forward- and backward-compatibility in mind. Thus old applications will
  75 work with new versions of the shared library, and new applications can work
  76 with old versions of the shared library (modulo any dependency on newer
  77 features, whose absence can be gracefully detected at runtime).
  78
  79 ## C System API
  80 Once Mojo is initialized within a process, the public
  81 [**C System API**](/mojo/public/c/system/README.md) is usable on any thread for
  82 the remainder of the process's lifetime. This encapsulates Mojo Core's stable
  83 ABI and comprises the total public API surface of the Mojo Core library.
  84
  85 The C System library's only dependency (apart from the system libc and e.g.
  86 pthreads) is Mojo Core itself. As such, it's possible build a fully-featured
  87 multiprocess system using only Mojo Core and its exposed C API. It exposes the
  88 fundamental cross-platform capabilities to create and manipulate Mojo primitives
  89 like **message pipes**, **data pipes**, and **shared buffers**, as well as APIs
  90 to help bootstrap connections among processes.
  91
  92 Despite this, it's rare for applications to use the C API directly. Instead this
  93 API acts as a stable foundation upon which several higher-level and more
  94 ergonomic Mojo libraries are built.
  95
  96 ## Platform Support API
  97 Mojo provides a small collection of abstractions around platform-specific IPC
  98 primitives to facilitate bootstrapping Mojo IPC between two processes. See the
  99 [Platform API](/mojo/public/cpp/platform/README.md) documentation for details.
 100
 101 ## Higher-Level System APIs
 102 There is a relatively small, higher-level system API for each supported
 103 language, built upon the low-level C API. Like the C API, direct usage of these
 104 system APIs is rare compared to the bindings APIs, but it is sometimes desirable
 105 or necessary.
 106
 107 These APIs provide wrappers around low-level [system API](#C-System-API)
 108 concepts, presenting interfaces that are more idiomatic for the target language:
 109
 110 - [**C++ System API**](/mojo/public/cpp/system/README.md)
 111 - [**JavaScript System API**](/third_party/blink/renderer/core/mojo/README.md)
 112 - [**Java System API**](/mojo/public/java/system/README.md)
 113
 114 ## Bindings APIs
 115 The [**mojom Interface Definition Language (IDL)**](/mojo/public/tools/bindings/README.md)
 116 is used to generate interface bindings for various languages to send and receive
 117 mojom interface messages using Mojo message pipes. The generated code is
 118 supported by a language-specific bindings API:
 119
 120 - [**C++ Bindings API**](/mojo/public/cpp/bindings/README.md)
 121 - [**JavaScript Bindings API**](/mojo/public/js/README.md)
 122 - [**Java Bindings API**](/mojo/public/java/bindings/README.md)
 123
 124 Note that the C++ bindings see the broadest usage in Chromium and are thus
 125 naturally the most feature-rich, including support for things like
 126 [associated interfaces](/mojo/public/cpp/bindings/README.md#Associated-Interfaces),
 127 [synchronous calls](/mojo/public/cpp/bindings/README.md#Synchronous-Calls), and
 128 [type-mapping](/mojo/public/cpp/bindings/README.md#Type-Mapping).
 129
 130 ## FAQ
 131
 132 ### Why not protobuf? Why a new thing?
 133 There are number of potentially decent answers to this question, but the
 134 deal-breaker is that a useful IPC mechanism must support transfer of native
 135 object handles (*e.g.* file descriptors) across process boundaries. Other
 136 non-new IPC things that do support this capability (*e.g.* D-Bus) have their own
 137 substantial deficiencies.
 138
 139 ### Are message pipes expensive?
 140 No. As an implementation detail, creating a message pipe is essentially
 141 generating two random numbers and stuffing them into a hash table, along with a
 142 few tiny heap allocations.
 143
 144 ### So really, can I create like, thousands of them?
 145 Yes! Nobody will mind. Create millions if you like. (OK but maybe don't.)
 146
 147 ### What are the performance characteristics of Mojo?
 148 Compared to the old IPC in Chrome, making a Mojo call is about 1/3 faster and uses
 149 1/3 fewer context switches. The full data is [available here](https://docs.google.com/document/d/1n7qYjQ5iy8xAkQVMYGqjIy_AXu2_JJtMoAcOOupO_jQ/edit).
 150
 151 ### Can I use in-process message pipes?
 152 Yes, and message pipe usage is identical regardless of whether the pipe actually
 153 crosses a process boundary -- in fact the location of the other end of a pipe is
 154 intentionally obscured, in part for the sake of efficiency, and in part to
 155 discourage tight coupling of application logic to such details.
 156
 157 Message pipes which don't cross a process boundary are efficient: sent messages
 158 are never copied, and a write on one end will synchronously modify the message
 159 queue on the other end. When working with generated C++ bindings, for example,
 160 the net result is that a `Remote` on one thread sending a message to a
 161 `Receiver` on another thread (or even the same thread) is effectively a
 162 `PostTask` to the `Binding`'s `TaskRunner` with the added -- but often small --
 163 costs of serialization, deserialization, validation, and some internal routing
 164 logic.
 165
 166 ### What about ____?
 167
 168 Please post questions to
 169 [`chromium-mojo@chromium.org`](https://groups.google.com/a/chromium.org/forum/#!forum/chromium-mojo)!
 170 The list is quite responsive.
 171