[−][src]Crate essrpc
Electron's Super Simple RPC (ESSRPC) is a lightweight RPC library which aims to enable RPC calls as transparently as possible through calls to ordinary trait methods.
The magic is performed by the essrpc
attribute macro which may
be applied to any trait whose functions each meet the following conditions:
- Returns a
Result
whose error type implementsFrom<RPCError>
. - Uses only parameter and returns types which implement
Serialize
- Is not unsafe
The essrpc
macro generates for a trait an RPC client and a
server. For a trait named Foo
, the macro will generate
FooRPCClient
which implements both
RPCClient and Foo
as well as
FooRPCServer
which implements RPCServer.
Examples
A trait can apply the essrpc
attribute like this.
#[essrpc] pub trait Foo { fn bar(&self, a: String, b: i32) -> Result<String, SomeError>; }
For example purposes, assume we're using a unix socket to
communicate between a parent and child process. Anything else
implementing Read+Write
would work just as well.
let (s1, s2) = UnixStream::pair().unwrap();
We can spin up a server like this
let mut s = FooRPCServer::new(FooImpl::new(), BincodeTransport::new(s2)); s.serve()
Then, if we have some type FooImpl
which implements Foo
, we can do RPC like this.
let client = FooRPCClient::new(BincodeTransport::new(s1)); match client.bar("the answer".to_string(), 42) { Ok(result) => assert_eq!("the answer is 42", result), Err(e) => panic!("error: {:?}", e) }
Asynchronous Clients
By default, the #[essrpc]
attribute generates a synchronous
client. Asynchronous clients can be generated via
#[essrpc(async)]
, or #[essrpc(sync, async)]
if both
synchronous and asynchronous clients are needed. For asynchronous,
the macro generates a new trait, suffixed with Async
for which
every method returns a boxed Future
instead of a Result
, with
the same success and error types, and a type implementing
AsyncRPCClient
. For example,
#[essrpc(async)] pub trait Foo { fn bar(&self, a: String, b: i32) -> Result<String, SomeError>; }
Would generate a FooAsync
trait with a bar
method returning
Box<Future<Item=String, Error=SomeError>>
and a
FooAsyncRPCClient
struct implementing both FooAsync
and
AsyncRPCClient.
Re-exports
pub use essrpc_macros::essrpc; |
Modules
transports |
|
Structs
GenericSerializableError | Generic serializable error with a description and optional cause. Used in conjunction with RPCError. |
MethodId | Identifies a method by both a name and an index. The Indices are automatically generated in the order methods are listed on the trait. Used when implementing ClientTransport |
RPCError | RPC error. All functions in RPC traits must return an error type
which implements |
Enums
PartialMethodId | Identifies a method by either a name or an index. Used when implementing ServerTransport. |
RPCErrorKind | Types of RPCError |
Traits
AsyncClientTransport | Trait for RPC transport (client) to be used with asynchronous clients |
AsyncRPCClient | Trait implemented by all RPC clients generated by the |
ClientTransport | Trait for RPC transport (client). ESSRPC attempts to make as few assumptions about the transport as possible. A transport may work across a network, via any IPC mechanism, or purely in memory within a single process. Often, you will implement both ClientTransport and ServerTransport on the same type, but it is permitted for the implementations to be on separate types. Obviously, they must be compatible. |
RPCClient | Trait implemented by all RPC clients generated by the |
RPCServer | Trait implemented by all RPC servers generated by the |
ServerTransport | Trait for RPC transport (server). ESSRPC attempts to make as few assumptions about the transport as possible. A transport may work across a network, via any IPC mechanism, or purely in memory within a single process. |