37 releases
0.8.2 | Sep 27, 2024 |
---|---|
0.8.1 | Aug 29, 2023 |
0.8.0 | Jun 19, 2023 |
0.7.2 | Sep 25, 2024 |
0.1.0 | Sep 23, 2019 |
#66 in Network programming
25,247 downloads per month
Used in 5 crates
(2 directly)
180KB
4.5K
SLoC
ttrpc-rust
ttrpc-rust is a non-core subproject of containerd
ttrpc-rust
is the Rust version of ttrpc. ttrpc is GRPC for low-memory environments.
The ttrpc compiler of ttrpc-rust
ttrpc_rust_plugin
is modified from gRPC compiler of gRPC-rs grpcio-compiler.
Usage
1. Generate with protoc
command
To generate the sources from proto files:
-
Install protoc from github.com/protocolbuffers/protobuf
-
Install protobuf-codegen
cargo install --force protobuf-codegen
- Install ttrpc_rust_plugin from ttrpc-rust/compiler
cd ttrpc-rust/compiler
cargo install --force --path .
- Generate the sources:
$ protoc --rust_out=. --ttrpc_out=. --plugin=protoc-gen-ttrpc=`which ttrpc_rust_plugin` example.proto
2. Generate programmatically
API to generate .rs files to be used e. g. from build.rs.
Example code:
fn main() {
protoc_rust_ttrpc::Codegen::new()
.out_dir("protocols")
.inputs(&[
"protocols/protos/agent.proto",
])
.include("protocols/protos")
.rust_protobuf() // also generate protobuf messages, not just services
.run()
.expect("Codegen failed.");
}
async/.await
ttrpc-rust supports async/.await. By using async/.await you can reduce the overhead and resource consumption caused by threads.
Usage
1. Generate codes in async version
Currently we only support generating async codes by using ttrpc-codegen
ttrpc_codegen::Codegen::new()
.out_dir("protocols/asynchronous")
.inputs(&protos)
.include("protocols/protos")
.rust_protobuf()
.customize(Customize {
async_all: true, // It's the key option.
..Default::default()
})
.run()
.expect("Gen async codes failed.");
Provide customize option
async_all
: generate async codes for both server and clientasync_server
: generate async codes for serverasync_client
: generate async codes for client
See more in
example/build.rs
2. Write your implemention in async/.await's way
Please follow the guidlines in example/async-server.rs
and example/async-client.rs
Run Examples
-
Go to the directory
$ cd ttrpc-rust/example
-
Start the server
$ cargo run --example server
or
$ cargo run --example async-server
-
Start a client
$ cargo run --example client
or
$ cargo run --example async-client
Notes: the version of protobuf
protobuf-codegen, ttrpc_rust_plugin and your code should use the same version protobuf. You will get following fail if use the different version protobuf.
27 | const _PROTOBUF_VERSION_CHECK: () = ::protobuf::VERSION_2_8_0;
| ^^^^^^^^^^^^^ help: a constant with a similar name exists: `VERSION_2_10_1`
The reason is that files generated by protobuf-codegen are compatible only with the same version of runtime
To fix this issue:
- Rebuild protobuf-codegen with new protobuf:
cd grpc-rs
cargo clean
cargo update
cargo install --force protobuf-codegen
- Rebuild ttrpc_rust_plugin with new protobuf:
cd ttrpc-rust/compiler
cargo clean
cargo update
cargo install --force --path .
- Build your project.
Dependencies
~3–15MB
~195K SLoC