OLD | NEW |
1 Mojo | 1 # ![Mojo Graphic](https://goo.gl/6CdlbH) Mojo |
2 ==== | 2 This document is a subset of the [Mojo documentation](/mojo). |
3 | 3 |
4 [Mojo](https://www.chromium.org/developers/design-documents/mojo) is an IPC & | 4 [TOC] |
5 binding mechanism for Chromium. | |
6 | 5 |
7 TODO(rockot): Describe the important subdirectories. | 6 ## Getting Started With Mojo |
| 7 |
| 8 To get started using Mojo in applications which already support it (such as |
| 9 Chrome), the fastest path forward will be to look at the bindings documentation |
| 10 for your language of choice ([**C++**](#C_Bindings), |
| 11 [**JavaScript**](#JavaScript-Bindings), or [**Java**](#Java-Bindings)) as well |
| 12 as the documentation for the |
| 13 [**Mojom IDL and bindings generator**](/mojo/public/tools/bindings). |
| 14 |
| 15 If you're looking for information on creating and/or connecting to services, see |
| 16 the top-level [Services documentation](/services). |
| 17 |
| 18 For specific details regarding the conversion of old things to new things, check |
| 19 out [Converting Legacy Chrome IPC To Mojo](/ipc). |
| 20 |
| 21 ## System Overview |
| 22 |
| 23 Mojo is a layered collection of runtime libraries providing a platform-agnostic |
| 24 abstraction of common IPC primitives, a message IDL format, and a bindings |
| 25 library with code generation for multiple target languages to facilitate |
| 26 convenient message passing across arbitrary inter- and intra-process boundaries. |
| 27 |
| 28 The documentation here is segmented according to the different isolated layers |
| 29 and libraries comprising the system. The basic hierarchy of features is as |
| 30 follows: |
| 31 |
| 32 ![Mojo Library Layering: EDK on bottom, different language bindings on top, publ
ic system support APIs in the middle](https://docs.google.com/drawings/d/1aNbLfF
-fejgzxCxH_b8xAaCVvftW8BGTH_EHD7nvU1w/pub?w=570&h=327) |
| 33 |
| 34 ## Embedder Development Kit (EDK) |
| 35 Every process to be interconnected via Mojo IPC is called a **Mojo embedder** |
| 36 and needs to embed the |
| 37 [**Embedder Development Kit (EDK)**](/mojo/edk/embedder) library. The EDK |
| 38 exposes the means for an embedder to physically connect one process to another |
| 39 using any supported native IPC primitive (*e.g.,* a UNIX domain socket or |
| 40 Windows named pipe) on the host platform. |
| 41 |
| 42 Details regarding where and how an application process actually embeds and |
| 43 configures the EDK are generaly hidden from the rest of the application code, |
| 44 and applications instead use the public System and Bindings APIs to get things |
| 45 done within processes that embed Mojo. |
| 46 |
| 47 ## C System API |
| 48 Once the EDK is initialized within a process, the public |
| 49 [**C System API**](/mojo/public/c/system) is usable on any thread for the |
| 50 remainder of the process's lifetime. This is a lightweight API with a relatively |
| 51 small (and eventually stable) ABI. Typically this API is not used directly, but |
| 52 it is the foundation upon which all remaining upper layers are built. It exposes |
| 53 the fundamental capabilities to create and interact with various types of Mojo |
| 54 handles including **message pipes**, **data pipes**, and **shared buffers**. |
| 55 |
| 56 ## High-Level System APIs |
| 57 |
| 58 There is a relatively small, higher-level system API for each supported |
| 59 language, built upon the low-level C API. Like the C API, direct usage of these |
| 60 system APIs is rare compared to the bindings APIs, but it is sometimes desirable |
| 61 or necessary. |
| 62 |
| 63 ### C++ |
| 64 The [**C++ System API**](/mojo/public/cpp/system) provides a layer of |
| 65 C++ helper classes and functions to make safe System API usage easier: |
| 66 strongly-typed handle scopers, synchronous waiting operations, system handle |
| 67 wrapping and unwrapping helpers, common handle operations, and utilities for |
| 68 more easily watching handle state changes. |
| 69 |
| 70 ### JavaScript |
| 71 The [**JavaScript APIs**](/mojo/public/js) are WIP. :) |
| 72 |
| 73 ### Java |
| 74 The [**Java System API**](/mojo/public/java/system) provides helper classes for |
| 75 working with Mojo primitives, covering all basic functionality of the low-level |
| 76 C API. |
| 77 |
| 78 ## High-Level Bindings APIs |
| 79 Typically developers do not use raw message pipe I/O directly, but instead |
| 80 define some set of interfaces which are used to generate code that message pipe |
| 81 usage feel like a more idiomatic method-calling interface in the target |
| 82 language of choice. This is the bindings layer. |
| 83 |
| 84 ### Mojom IDL and Bindings Generator |
| 85 Interfaces are defined using the [**Mojom IDL**](/mojo/public/tools/bindings), |
| 86 which can be fed to the [**bindings generator**](/mojo/public/tools/bindings) to |
| 87 generate code in various supported languages. Generated code manages |
| 88 serialization and deserialization of messages between interface clients and |
| 89 implementations, simplifying the code -- and ultimately hiding the message pipe |
| 90 -- on either side of an interface connection. |
| 91 |
| 92 ### C++ Bindings |
| 93 By far the most commonly used API defined by Mojo, the |
| 94 [**C++ Bindings API**](/mojo/public/cpp/bindings) exposes a robust set of |
| 95 features for interacting with message pipes via generated C++ bindings code, |
| 96 including support for sets of related bindings endpoints, associated interfaces, |
| 97 nested sync IPC, versioning, bad-message reporting, arbitrary message filter |
| 98 injection, and convenient test facilities. |
| 99 |
| 100 ### JavaScript Bindings |
| 101 The [**JavaScript APIs**](/mojo/public/js) are WIP. :) |
| 102 |
| 103 ### Java Bindings |
| 104 The [**Java Bindings API**](/mojo/public/java/bindings) provides helper classes |
| 105 for working with Java code emitted by the bindings generator. |
| 106 |
| 107 ## FAQ |
| 108 |
| 109 ### Why not protobuf? Why a new thing? |
| 110 There are number of potentially decent answers to this question, but the |
| 111 deal-breaker is that a useful IPC mechanism must support transfer of native |
| 112 object handles (*e.g.* file descriptors) across process boundaries. Other |
| 113 non-new IPC things that do support this capability (*e.g.* D-Bus) have their own |
| 114 substantial deficiencies. |
| 115 |
| 116 ### Are message pipes expensive? |
| 117 No. As an implementation detail, creating a message pipe is essentially |
| 118 generating two random numbers and stuffing them into a hash table, along with a |
| 119 few tiny heap allocations. |
| 120 |
| 121 ### So really, can I create like, thousands of them? |
| 122 Yes! Nobody will mind. Create millions if you like. (OK but maybe don't.) |
| 123 |
| 124 ### Can I use in-process message pipes? |
| 125 Yes, and message pipe usage is identical regardless of whether the pipe actually |
| 126 crosses a process boundary -- in fact this detail is intentionally obscured. |
| 127 |
| 128 Message pipes which don't cross a process boundary are efficient: sent messages |
| 129 are never copied, and a write on one end will synchronously modify the message |
| 130 queue on the other end. When working with generated C++ bindings, for example, |
| 131 the net result is that an `InterfacePtr` on one thread sending a message to a |
| 132 `Binding` on another thread (or even the same thread) is effectively a |
| 133 `PostTask` to the `Binding`'s `TaskRunner` with the added -- but often small -- |
| 134 costs of serialization, deserialization, validation, and some internal routing |
| 135 logic. |
| 136 |
| 137 ### What about ____? |
| 138 |
| 139 Please post questions to |
| 140 [`chromium-mojo@chromium.org`](https://groups.google.com/a/chromium.org/forum/#!
forum/chromium-mojo)! |
| 141 The list is quite responsive. |
| 142 |
OLD | NEW |