pub trait Service {
type Request;
type Response;
type Error;
type Future: Future<Output = Result<Self::Response, Self::Error>>;
// Required methods
fn poll_ready(
&mut self,
ctx: &mut Context<'_>,
) -> Poll<Result<(), Self::Error>>;
fn call(&mut self, req: Self::Request) -> Self::Future;
// Provided methods
fn map<F, R>(self, f: F) -> Map<Self, F, R>
where Self: Sized,
F: FnMut(Self::Response) -> R { ... }
fn map_err<F, E>(self, f: F) -> MapErr<Self, F, E>
where Self: Sized,
F: Fn(Self::Error) -> E { ... }
}Expand description
An asynchronous operation from Request to a Response.
The Service trait models a request/response interaction, receiving requests and returning
replies. You can think about a service as a function with one argument that returns some result
asynchronously. Conceptually, the operation looks like this:
async fn(Request) -> Result<Response, Err>The Service trait just generalizes this form where each parameter is described as an
associated type on the trait. Services can also have mutable state that influence computation.
Service provides a symmetric and uniform API; the same abstractions can be used to represent
both clients and servers. Services describe only transformation operations which encourage
simple API surfaces. This leads to simpler design of each service, improves test-ability and
makes composition easier.
struct MyService;
impl Service for MyService {
type Request = u8;
type Response = u64;
type Error = MyError;
type Future = Pin<Box<Future<Output=Result<Self::Response, Self::Error>>>>;
fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { ... }
fn call(&mut self, req: Self::Request) -> Self::Future { ... }
}Sometimes it is not necessary to implement the Service trait. For example, the above service could be rewritten as a simple function and passed to fn_service.
async fn my_service(req: u8) -> Result<u64, MyError>;Required Associated Types§
Required Methods§
Sourcefn poll_ready(&mut self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>
fn poll_ready(&mut self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>
Returns Ready when the service is able to process requests.
If the service is at capacity, then Pending is returned and the task
is notified when the service becomes ready again. This function is
expected to be called while on a task.
This is a best effort implementation. False positives are permitted.
It is permitted for the service to return Ready from a poll_ready
call and the next invocation of call results in an error.
§Notes
.poll_ready()might be called on different task from actual service call.- In case of chained services,
.poll_ready()get called for all services at once.
Sourcefn call(&mut self, req: Self::Request) -> Self::Future
fn call(&mut self, req: Self::Request) -> Self::Future
Process the request and return the response asynchronously.
This function is expected to be callable off task. As such,
implementations should take care to not call poll_ready. If the
service is at capacity and the request is unable to be handled, the
returned Future should resolve to an error.
Calling call without calling poll_ready is permitted. The
implementation must be resilient to this fact.
Provided Methods§
Sourcefn map<F, R>(self, f: F) -> Map<Self, F, R>
fn map<F, R>(self, f: F) -> Map<Self, F, R>
Map this service’s output to a different type, returning a new service of the resulting type.
This function is similar to the Option::map or Iterator::map where
it will change the type of the underlying service.
Note that this function consumes the receiving service and returns a
wrapped version of it, similar to the existing map methods in the
standard library.
Sourcefn map_err<F, E>(self, f: F) -> MapErr<Self, F, E>
fn map_err<F, E>(self, f: F) -> MapErr<Self, F, E>
Map this service’s error to a different error, returning a new service.
This function is similar to the Result::map_err where it will change
the error type of the underlying service. For example, this can be useful to
ensure that services have the same error type.
Note that this function consumes the receiving service and returns a wrapped version of it.