Struct plumbing::Pipeline

pub struct Pipeline<Si, St: Stream + Unpin> { /* fields omitted */ }

A Pipeline manages sending requests through a stream and retrieving their matching responses.

A pipeline manages request/response flow through a [Sink] and associated [Stream]. The two halves should be set up such that:

• Items sent into the [Sink] are submitted to some underlying system as requests.
• That system replies to each request with a response, in order, via the [Stream].

This could be HTTP requests sent through a Keep-Alive connection, Redis interactions through the Redis Protocol, or anything else.

The Pipeline provides a submit method, which submits a request. Pipelines are backpressure sensitive, so this method will block until the underlying [Sink] can accept it. Pipelines do not do any extra buffering, so if you’re using it to enqueue several requests at once, be sure that the [Sink] has been set up with its own buffering.

The submit method will return a Resolver associated with that request. This Resolver is a future which will, when awaited, resolve to the response associated with the Request. These resolvers must be awaited or dropped in order to consume responses from the underlying stream; be sure to set up concurrency or buffering to ensure your request submissions don’t get stuck because the system is waiting for a response to be collected.

Implementations

impl<Si: Unpin, St: Unpin + Stream> Pipeline<Si, St>

pub fn new<T>(requests: Si, responses: St) -> Self where
    Si: Sink<T>, 

Construct a new Pipeline with associated channels for requests and responses. In order for the Pipeline’s logic to function correctly, this pair must be set up such that each request submitted through requests eventually results in a response being sent back through responses, in order.

pub async fn submit<T>(&mut self, item: T) -> Result<Resolver<St>, Si::Error> where
    Si: Sink<T>, 

Submit a request to this Pipeline, blocking until it can be sent to the underlying Sink. Returns a Resolver that can be used to await the response, or an error if the Sink returned an error.

pub async fn submit_owned<T>(
    self,
    item: T
) -> (Self, Result<Resolver<St>, Si::Error>) where
    Si: Sink<T>, 

Submit a request to this Pipeline. Same as submit, but this takes self by move and returns it as part of the result, which can make it easier to construct chained futures (for instance, via [.then][FutureExt::then]).

pub async fn flush<T>(&mut self) -> Result<(), Si::Error> where
    Si: Sink<T>, 

Flush the underlying Sink, blocking until it’s finished. Note that, depending on your request/response system, you may also need to be sure that any incomplete Resolvers are also being awaited so that the responses can be drained; this method only handles flushing the requests side. The flush_and method is a helper for this.

pub async fn flush_and<T, F>(&mut self, fut: F) -> Result<F::Output, Si::Error> where
    Si: Sink<T>,
    F: Future, 

Flush the underlying sink while awaiting polling the given future. If the flush encounters an error, that error will be returned. If the future completes before the flush is finished, the result of the future will be returned immediately. If the flush finishes, this will continue blocking until the given future is complete.

This is a helper function designed to help ensure the requests are pushed concurrently with reading responses with Resolvers. It tries to perform a lazy amount of flushing work; it only polls flush while the given future hasn’t resolved.

impl<Si, St: Stream + Unpin> Pipeline<Si, St>

pub async fn finish(self) -> (Si, Option<Skip<St>>)

Finish the pipeline. Wait for all the Resolvers to complete (or abort), then return the original sink & stream. If the stream completed during the resolvers, return None instead of the stream.

Note that this method will not do any additional request flushing, so be sure that all of the remaining resolvers are able to complete.

This function returns a Skip<St> so that any responses associated with aborted Resolvers will be skipped.

Trait Implementations

impl<Si: Debug, St: Debug + Stream + Unpin> Debug for Pipeline<Si, St>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.