Consuming
Consumers are used to consume the service API on the client side.
Creating a consumer
The #[api] macro generates a Consumer type for your API trait.
Create it with Consumer::consume function over a dnet transport:
use dnet::rpc::Consume;
use dnet::{codecs::BincodeCodec, tcp::TcpTransport};
let stream = tokio::net::TcpStream::connect(address).await?;
let transport = TcpTransport::buffered(stream, BincodeCodec::default());
let consumer = Consumer::consume(transport, Default::default(), Default::default());
Calling remote methods
Once the consumer is created, you call remote methods as ordinary async Rust methods:
consumer.hello_world().await?;
let sum = consumer.add_numbers(2, 3).await?;
Consumer methods return (after awaiting) a Result which error is Error inside rpc module.
Stream methods
If the API declares a streaming method, the consumer call returns a stream handle:
let mut time_stream = consumer.stream_time(std::time::Duration::from_secs(1)).await?;
Note
Notice that you have to await your streaming request first - only then you will receive an actual stream instance.
You can then read values from the stream until it closes:
use futures::StreamExt;
while let Some(time) = time_stream.next().await {
println!("Time: {}", time);
}
Streaming consumer methods return type Stream inside rpc’s consumer module.
Aborting requests and streams
Generated request futures and stream handles support aborting.
For example:
use tokio::time::{sleep, Duration};
let mut long_task_future = consumer.long_task();
let aborter = long_task_future.aborter();
tokio::select! {
result = &mut long_task_future => {
println!("Task completed: {result:?}");
}
_ = sleep(Duration::from_secs(10)) => {
aborter.abort();
println!("Task aborted due to taking too long.");
}
}
Notes
- A consumer can make many requests over the same transport.
- Each request is matched to a response using an internal request ID.
- Streaming values are delivered in order until the producer closes the stream.