pub trait Service<Req> {
type Response;
type Error;
type Future: Future<Output = Result<Self::Response, Self::Error>>;
// Required methods
fn poll_ready(&self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;
fn call(&self, req: Req) -> Self::Future;
}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. Requests are defined as a generic type parameter
and responses and other details are defined as associated types on the trait impl. Notice that
this design means that services can receive many request types and converge them to a single
response type.
Services can also have mutable state that influence computation by using a Cell, RefCell
or Mutex. Services intentionally do not take &mut self to reduce overhead in the
common cases.
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<u8> for MyService {
type Response = u64;
type Error = MyError;
type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;
fn poll_ready(&self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { ... }
fn call(&self, req: u8) -> 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>;
let svc = fn_service(my_service)
svc.call(123)Required Associated Types§
Required Methods§
sourcefn poll_ready(&self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>
fn poll_ready(&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_readymight be called on a different task tocall.- In cases of chained services,
.poll_ready()is called for all services at once.
sourcefn call(&self, req: Req) -> Self::Future
fn call(&self, req: Req) -> Self::Future
Process the request and return the response asynchronously.
This function is expected to be callable off-task. As such, implementations of call 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.
Invoking call without first invoking poll_ready is permitted. Implementations must be
resilient to this fact.
Implementations on Foreign Types§
source§impl Service<Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>>> for ExpectHandler
impl Service<Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>>> for ExpectHandler
type Response = Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>>
type Error = Error
type Future = Ready<Result<<ExpectHandler as Service<Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>>>>::Response, <ExpectHandler as Service<Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>>>>::Error>>
fn poll_ready( &self, _: &mut Context<'_> ) -> Poll<Result<(), <ExpectHandler as Service<Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>>>>::Error>>
fn call( &self, req: Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>> ) -> <ExpectHandler as Service<Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>>>>::Future
source§impl<T> Service<(Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>>, Framed<T, Codec>)> for UpgradeHandler
impl<T> Service<(Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>>, Framed<T, Codec>)> for UpgradeHandler
type Response = ()
type Error = Error
type Future = Pin<Box<dyn Future<Output = Result<<UpgradeHandler as Service<(Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>>, Framed<T, Codec>)>>::Response, <UpgradeHandler as Service<(Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>>, Framed<T, Codec>)>>::Error>>, Global>>
fn poll_ready( &self, _: &mut Context<'_> ) -> Poll<Result<(), <UpgradeHandler as Service<(Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>>, Framed<T, Codec>)>>::Error>>
fn call( &self, _: (Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>>, Framed<T, Codec>) ) -> <UpgradeHandler as Service<(Request<Pin<Box<dyn Stream<Item = Result<Bytes, PayloadError>>, Global>>>, Framed<T, Codec>)>>::Future
source§impl<S, Req> Service<Req> for RefCell<S>where
S: Service<Req>,
impl<S, Req> Service<Req> for RefCell<S>where S: Service<Req>,
This impl is deprecated since v2 because the Service trait now receives shared reference.