5 ## Getting Started With Mojo
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 & Services](/docs/mojo_and_services.md) guide.
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)
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 & Services](/docs/README.md#Mojo-Services) documentation.
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.
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:
34 ![Mojo Library Layering: Core on bottom, language bindings on top, public system support APIs in the middle](/docs/images/mojo_stack.png)
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.
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.
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.
54 To support other scenarios, use 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.
61 In order to take advantage of this mechanism, the library's binary must be
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
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.
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).
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.
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.
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.
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.
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
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:
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)
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:
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)
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).
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.
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.
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.)
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).
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.
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
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.