Mojo C++ Platform API

This document is a subset of theMojo documentation.

Overview

The Mojo C++ Platform API provides a lightweight set of abstractions around stable platform primitive APIs like UNIX domain sockets and Windows named pipes. This API is primarily useful in conjunction with MojoInvitations to bootstrap Mojo IPC between two processes.

Platform Handles

ThePlatformHandle type provides a move-only wrapper around an owned, platform-specific primitive handle types. The type of primitive it holds can be any of the following:

• Windows HANDLE (Windows only)
• Fuchsia zx_handle_t (Fuchsia only)
• Mach send right (OSX only)
• POSIX file descriptor (POSIX systems only)

See theheader for more details.

Platform Channels

ThePlatformChannel type abstracts a platform-specific IPC FIFO primitive primarily for use with the MojoInvitations API. Constructing aPlatformChannel instance creates the underlying system primitive with two transferrablePlatformHandle instances, each thinly wrapped as aPlatformChannelEndpoint for additional type-safety. One endpoint is designated aslocal and the otherremote, the intention being that the remote endpoint will be transferred to another process in the system.

See theheader for more details. See theInvitations documentation for an example of usingPlatformChannel with an invitation to bootstrap IPC between a process and one of its newly launched child processes.

Named Platform Channels

For cases where it is not feasible to transfer aPlatformHandle from one running process to another, the Platform API also providesNamedPlatformChannel, which abstracts a named system resource that can facilitate communication similarly toPlatformChannel.

ANamedPlatformChannel upon construction will begin listening on a platform-specific primitive (a named pipe server on Windows, a domain socket server on POSIX,etc.). The globally reachable name of the server (e.g. the socket path) can be specified at construction time viaNamedPlatformChannel::Options::server_name, but if no name is given, a suitably random one is generated and used.

// In one processmojo::NamedPlatformChannel::Options options;mojo::NamedPlatformChannel named_channel(options);OutgoingInvitation::Send(std::move(invitation),                         named_channel.TakeServerEndpoint());SendServerNameToRemoteProcessSomehow(named_channel.GetServerName());// In the other processvoidOnGotServerName(const mojo::NamedPlatformChannel::ServerName& name){// Connect to the server.  mojo::PlatformChannelEndpoint endpoint=      mojo::NamedPlatformChannel::ConnectToServer(name);// Proceed normally with invitation acceptance.auto invitation= mojo::IncomingInvitation::Accept(std::move(endpoint));// ...}