pub trait Channelwhere
Self: Transport<Response<Self::Resp>, TrackedRequest<Self::Req>>,{
type Req;
type Resp;
type Transport;
// Required methods
fn config(&self) -> &Config;
fn in_flight_requests(&self) -> usize;
fn transport(&self) -> &Self::Transport;
// Provided methods
fn max_concurrent_requests(self, limit: usize) -> MaxRequests<Self>
where Self: Sized { ... }
fn requests(self) -> Requests<Self>
where Self: Sized { ... }
fn execute<S>(self, serve: S) -> TokioChannelExecutor<Requests<Self>, S> ⓘ
where Self: Sized,
S: Serve<Self::Req, Resp = Self::Resp> + Send + 'static,
S::Fut: Send,
Self::Req: Send + 'static,
Self::Resp: Send + 'static { ... }
}
Expand description
The server end of an open connection with a client, receiving requests from, and sending
responses to, the client. Channel
is a Transport
with request lifecycle management.
The ways to use a Channel, in order of simplest to most complex, is:
Channel::execute
- Requires thetokio1
feature. This method is best for those who do not have specific scheduling needs and whose services areSend + 'static
.Channel::requests
- This method is best for those who need direct access to individual requests, or are not usingtokio
, or want control over futures scheduling.Requests
is a stream ofInFlightRequests
, each which has anexecute
method. If usingexecute
, request processing will automatically cease when either the request deadline is reached or when a corresponding cancellation message is received by the Channel.Stream::next
/Sink::send
- A user is free to manually read requests from, and send responses into, a Channel in lieu of the previous methods. Channels streamTrackedRequests
, which, in addition to the request itself, contains the serverSpan
, request lifetime [AbortRegistration
], and an inertResponseGuard
. Wrapping response logic in an [Abortable
] future using the abort registration will ensure that the response does not execute longer than the request deadline. TheChannel
itself will clean up request state once either the deadline expires, or the response guard is dropped, or a response is sent.
Channels must be implemented using the decorator pattern: the only way to create a
TrackedRequest
is to get one from another Channel
. Ultimately, all TrackedRequests
are
created by BaseChannel
.
Required Associated Types§
Required Methods§
sourcefn in_flight_requests(&self) -> usize
fn in_flight_requests(&self) -> usize
Returns the number of in-flight requests over this channel.
Provided Methods§
sourcefn max_concurrent_requests(self, limit: usize) -> MaxRequests<Self>where
Self: Sized,
fn max_concurrent_requests(self, limit: usize) -> MaxRequests<Self>where Self: Sized,
Caps the number of concurrent requests to limit
. An error will be returned for requests
over the concurrency limit.
Note that this is a very simplistic throttling heuristic. It is easy to set a number that is too low for the resources available to the server. For production use cases, a more advanced throttler is likely needed.
sourcefn requests(self) -> Requests<Self>where
Self: Sized,
fn requests(self) -> Requests<Self>where Self: Sized,
Returns a stream of requests that automatically handle request cancellation and response routing.
This is a terminal operation. After calling requests
, the channel cannot be retrieved,
and the only way to complete requests is via Requests::execute
or
InFlightRequest::execute
.
sourcefn execute<S>(self, serve: S) -> TokioChannelExecutor<Requests<Self>, S> ⓘwhere
Self: Sized,
S: Serve<Self::Req, Resp = Self::Resp> + Send + 'static,
S::Fut: Send,
Self::Req: Send + 'static,
Self::Resp: Send + 'static,
fn execute<S>(self, serve: S) -> TokioChannelExecutor<Requests<Self>, S> ⓘwhere Self: Sized, S: Serve<Self::Req, Resp = Self::Resp> + Send + 'static, S::Fut: Send, Self::Req: Send + 'static, Self::Resp: Send + 'static,
tokio1
only.Runs the channel until completion by executing all requests using the given service function. Request handlers are run concurrently by spawning on tokio’s default executor.