actix_service

# Trait Service

source

    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§

source

#### type Response

Responses given by the service.

source

#### type Error

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

source

#### type Future: Future<Output = Result<Self::Response, Self::Error>>

The future response value.

## Required Methods§

source

#### 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

1. `poll_ready` might be called on a different task to `call`.
2. In cases of chained services, `.poll_ready()` is called for all services at once.

source

#### 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<'a, S, Req> Service<Req> for &'a S
where S: Service<Req> + 'a,

source §

#### type Response = <S as Service<Req>>::Response

source §

#### type Error = <S as Service<Req>>::Error

source §

#### type Future = <S as Service<Req>>::Future

source §

#### fn poll_ready(&self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>

source §

#### fn call(&self, request: Req) -> S::Future

source §

### impl<'a, S, Req> Service<Req> for &'a mut S
where S: Service<Req> + 'a,

source §

#### type Response = <S as Service<Req>>::Response

source §

#### type Error = <S as Service<Req>>::Error

source §

#### type Future = <S as Service<Req>>::Future

source §

#### fn poll_ready(&self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>

source §

#### fn call(&self, request: Req) -> S::Future

source §

### impl<S, Req> Service<Req> for Box<S>
where S: Service<Req> + ?Sized,

source §

#### type Response = <S as Service<Req>>::Response

source §

#### type Error = <S as Service<Req>>::Error

source §

#### type Future = <S as Service<Req>>::Future

source §

#### fn poll_ready(&self, ctx: &mut Context<'_>) -> Poll<Result<(), S::Error>>

source §

#### fn call(&self, request: Req) -> S::Future

source §

### impl<S, Req> Service<Req> for Rc<S>
where S: Service<Req> + ?Sized,

source §

#### type Response = <S as Service<Req>>::Response

source §

#### type Error = <S as Service<Req>>::Error

source §

#### type Future = <S as Service<Req>>::Future

source §

#### fn poll_ready(&self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>

source §

#### fn call(&self, request: Req) -> S::Future

source §

### 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.

source §

#### type Response = <S as Service<Req>>::Response

source §

#### type Error = <S as Service<Req>>::Error

source §

#### type Future = <S as Service<Req>>::Future

source §

#### fn poll_ready(&self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>

source §

#### fn call(&self, request: Req) -> S::Future

## Implementors§