Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.