Disclaimer: This is not an official Google product.
tarpc is an RPC framework for rust with a focus on ease of use. Defining a service can be done in just a few lines of code, and most of the boilerplate of writing a server is taken care of for you.
"RPC" stands for "Remote Procedure Call," a function call where the work of producing the return value is being done somewhere else. When an rpc function is invoked, behind the scenes the function contacts some other process somewhere and asks them to compute the function instead. The original function then returns the value produced by that other server.
Add to your Cargo.toml
dependencies:
tarpc = "0.3.0"
#[macro_use]
extern crate tarpc;
mod hello_service {
service! {
rpc hello(name: String) -> String;
}
}
use hello_service::Service as HelloService;
struct HelloServer;
impl HelloService for HelloServer {
fn hello(&self, name: String) -> String {
format!("Hello, {}!", name)
}
}
fn main() {
let server_handle = HelloServer.spawn("0.0.0.0:0").unwrap();
let client = hello_service::Client::new(server_handle.local_addr()).unwrap();
assert_eq!("Hello, Mom!", client.hello("Mom".into()).unwrap());
drop(client);
server_handle.shutdown();
}
The service!
macro expands to a collection of items that collectively form an rpc service. In the
above example, the macro is called within the hello_service
module. This module will contain a
Client
(and AsyncClient
) type, and a Service
trait. The trait provides default fn
s for
starting the service: spawn
and spawn_with_config
, which start the service listening on a tcp
port. A Client
(or AsyncClient
) can connect to such a service. These generated types make it
easy and ergonomic to write servers without dealing with sockets or serialization directly. See the
tarpc_examples package for more sophisticated examples.
Use cargo doc
as you normally would to see the documentation created for all
items expanded by a service!
invocation.
- Concurrent requests from a single client.
- Any type that
impl
sserde
'sSerialize
andDeserialize
can be used in the rpc signatures. - Attributes can be specified on rpc methods. These will be included on both the
Service
trait methods as well as on theClient
's stub methods. - Just like regular fns, the return type can be left off when it's
-> ()
. - Arg-less rpc's are also allowed.
- Automatically reconnect on the client side when the connection cuts out.
- Support asynchronous server implementations (currently thread per connection).
- Support generic serialization protocols.
To contribute to tarpc, please see CONTRIBUTING.
tarpc is distributed under the terms of the MIT license.
See LICENSE for details.