Ken Rockot | 7c05e3de | 2018-06-26 02:54:45 | [diff] [blame] | 1 | # Mojo C++ Platform API |
| 2 | This document is a subset of the [Mojo documentation](/mojo/README.md). |
| 3 | |
| 4 | [TOC] |
| 5 | |
| 6 | ## Overview |
| 7 | The Mojo C++ Platform API provides a lightweight set of abstractions around |
| 8 | stable platform primitive APIs like UNIX domain sockets and Windows named pipes. |
| 9 | This API is primarily useful in conjunction with Mojo |
| 10 | [Invitations](/mojo/public/cpp/system/README.md#Invitations) to bootstrap Mojo |
| 11 | IPC between two processes. |
| 12 | |
| 13 | ## Platform Handles |
| 14 | The `PlatformHandle` type provides a move-only wrapper around an owned, |
| 15 | platform-specific primitive handle types. The type of primitive it holds can be |
| 16 | any of the following: |
| 17 | |
| 18 | * Windows HANDLE (Windows only) |
| 19 | * Fuchsia zx_handle_t (Fuchsia only) |
| 20 | * Mach send right (OSX only) |
| 21 | * POSIX file descriptor (POSIX systems only) |
| 22 | |
| 23 | See the |
| 24 | [header](https://cs.chromium.org/src/mojo/public/cpp/platform/platform_handle.h) |
| 25 | for more details. |
| 26 | |
| 27 | ## Platform Channels |
| 28 | The `PlatformChannel` type abstracts a platform-specific IPC FIFO primitive |
| 29 | primarily for use with the Mojo |
| 30 | [Invitations](/mojo/public/cpp/system/README.md#Invitations) API. Constructing |
| 31 | a `PlatformChannel` instance creates the underlying system primitive with two |
| 32 | transferrable `PlatformHandle` instances, each thinly wrapped as a |
| 33 | `PlatformChannelEndpoint` for additional type-safety. One endpoint is designated |
| 34 | as **local** and the other **remote**, the intention being that the remote |
| 35 | endpoint will be transferred to another process in the system. |
| 36 | |
| 37 | See the |
| 38 | [header](https://cs.chromium.org/src/mojo/public/cpp/platform/platform_channel.h) |
| 39 | for more details. See the |
| 40 | [Invitations](/mojo/public/cpp/system/README.md#Invitations) documentation for |
| 41 | an example of using `PlatformChannel` with an invitation to bootstrap IPC |
| 42 | between a process and one of its newly launched child processes. |
| 43 | |
| 44 | ## Named Platform Channels |
| 45 | For cases where it is not feasible to transfer a `PlatformHandle` from one |
| 46 | running process to another, the Platform API also provides |
| 47 | `NamedPlatformChannel`, which abstracts a named system resource that can |
| 48 | facilitate communication similarly to `PlatformChannel`. |
| 49 | |
Eric Roman | c41635b | 2018-08-15 02:09:31 | [diff] [blame] | 50 | A `NamedPlatformChannel` upon construction will begin listening on a |
Ken Rockot | 7c05e3de | 2018-06-26 02:54:45 | [diff] [blame] | 51 | platform-specific primitive (a named pipe server on Windows, a domain socket |
| 52 | server on POSIX, *etc.*). The globally reachable name of the server (*e.g.* the |
| 53 | socket path) can be specified at construction time via |
| 54 | `NamedPlatformChannel::Options::server_name`, but if no name is given, a |
| 55 | suitably random one is generated and used. |
| 56 | |
| 57 | ``` cpp |
| 58 | // In one process |
| 59 | mojo::NamedPlatformChannel::Options options; |
| 60 | mojo::NamedPlatformChannel named_channel(options); |
| 61 | OutgoingInvitation::Send(std::move(invitation), |
| 62 | named_channel.TakeServerEndpoint()); |
| 63 | SendServerNameToRemoteProcessSomehow(named_channel.GetServerName()); |
| 64 | |
| 65 | // In the other process |
| 66 | void OnGotServerName(const mojo::NamedPlatformChannel::ServerName& name) { |
| 67 | // Connect to the server. |
| 68 | mojo::PlatformChannelEndpoint endpoint = |
| 69 | mojo::NamedPlatformChannel::ConnectToServer(name); |
| 70 | |
| 71 | // Proceed normally with invitation acceptance. |
| 72 | auto invitation = mojo::IncomingInvitation::Accept(std::move(endpoint)); |
| 73 | // ... |
| 74 | } |
| 75 | ``` |