Trait ntex_service::Service

source · 
pub trait Service<Req> {
    type Response;
    type Error;
    type Future<'f>: Future<Output = Result<Self::Response, Self::Error>>
    where
        Req: 'f,
        Self: 'f;

    fn call(&self, req: Req) -> Self::Future<'_>;

    fn poll_ready(&self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { ... }
    fn poll_shutdown(&self, cx: &mut Context<'_>) -> Poll<()> { ... }
    fn map<F, Res>(self, f: F) -> Map<Self, F, Req, Res>
    where
        Self: Sized,
        F: Fn(Self::Response) -> Res,
    { ... }
    fn map_err<F, E>(self, f: F) -> MapErr<Self, Req, F, E>
    where
        Self: Sized,
        F: Fn(Self::Error) -> E,
    { ... }
}
Expand description

An asynchronous function of Request to a Response.

The Service trait represents a request/response interaction, receiving requests and returning replies. You can think about service as a function with one argument that returns some result asynchronously. Conceptually, the operation looks like this:

ⓘ
async fn(Request) -> Result<Response, Error>

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 = Infallible;
    type Future<'f> = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;

    fn call(&self, req: u8) -> Self::Future<'_> {
        Box::pin(std::future::ready(Ok(req as u64)))
    }
}

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, Infallible>;

Required Associated Types§

Responses given by the service.

Errors produced by the service when polling readiness or executing call.

The future response value.

Required Methods§

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.

Provided Methods§

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
  1. .poll_ready() might be called on different task from actual service call.
  2. In case of chained services, .poll_ready() is called for all services at once.

Shutdown service.

Returns Ready when the service is properly shutdowns. This method might be called after it returns Ready.

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.

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. This is useful for example to ensure that services have the same error type.

Note that this function consumes the receiving service and returns a wrapped version of it.

Implementations on Foreign Types§

Implementors§