Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(152)

Side by Side Diff: mojo/README.md

Issue 2783223004: Adds lots of Mojo documentation (Closed)
Patch Set: Created 3 years, 8 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
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
OLDNEW
« ipc/README.md ('K') | « ipc/README.md ('k') | mojo/edk/embedder/README.md » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698