Crate ipc_rpc

source · [−]
Expand description

Inter-Process Communication Remote Procedure Calls

Crates.io

This Rust library is a wrapper over servo/ipc-channel that adds many new features.

  • Bi-directional communication by default.
  • Future based reply mechanism allows easy and accurate pairing of requests and responses.
  • (Optional, enabled by default) Validation on startup that message schemas match between the server and client. No more debugging bad deserializations. Relies on schemars.
  • Streamlined initialization of IPC channels for common use cases, while still allowing for more flexible and robust dynamic initialization in more unique scenarios.

Compatible with anything that can run servo/ipc-channel, which at time of writing includes

  • Windows
  • MacOS
  • Linux
  • FreeBSD
  • OpenBSD

Additionally, servo/ipc-channel supports the following platforms but only while in inprocess mode, which is not capable of communication between processes.

  • Android
  • iOS
  • WASI

tokio

This crate uses the tokio runtime for executing futures, and it is a hard requirement that users of ipc-rpc must use tokio. There are no plans to add support for other executors, but sufficient demand for other executors may change that.

Cargo features

This crate exposes one feature, message-schema-validation, which is on by default. This enables functionality related to the schemars crate. When enabled, the software will attempt to validate the user message schema on initialization of the connection. Failure to validate is not a critical failure, and won’t crash the program. An error will be emitted in the logs, and this status can be retrieved programmatically via many functions, all called schema_validated().

If you decide that a failure to validate the schema should be a critical failure you can add the following line of code to your program for execution after a connection is established.

Server

server.schema_validated().await.unwrap().assert_success();

Client

client.schema_validated().await.unwrap().assert_success();

Limitations

Much like servo/ipc-channel, servers may only serve one client. Overcoming this limitation would require work within servo/ipc-channel.

Macros

rpc_call
Invokes an RPC call within the current async runtime.

Structs

ConnectionKey
This key can be used to connect to the IPC server it came with, even outside of this process.
IpcRpc
Initializes a server and owns the connected client. This structure is the preferred way for servers to manage a relationship with a client.
IpcRpcBuilder
Builds an IpcRpc. This is initialized via IpcRpc::build()
IpcRpcClient
Used to send messages to the connected server.
IpcRpcServer
Used to send messages to the connected client (assuming one does connect)

Enums

ConnectionStatus
Reports the status of the connection between the server and the client
IpcRpcError
Errors which can occur with ipc-rpc during operation.
SchemaValidationStatus
Reports the outcome of automatic schema validation testing. This testing is performed on connection initiation.

Constants

DEFAULT_REPLY_TIMEOUT
The default timeout used for send() style methods. Use send_timeout() to use something else.

Traits

UserMessage
A combination trait which represents all of the traits needed for a type to be used as a message with this library.