pub trait Service<Req> {
type Response;
type Error;
// Required method
async fn call(
&self,
req: Req,
ctx: ServiceCtx<'_, Self>,
) -> Result<Self::Response, Self::Error>;
// Provided methods
async fn ready(&self, ctx: ServiceCtx<'_, Self>) -> Result<(), Self::Error> { ... }
async fn shutdown(&self) { ... }
fn poll(&self, cx: &mut Context<'_>) -> Result<(), Self::Error> { ... }
fn map<F, Res>(self, f: F) -> ServiceChain<Map<Self, F, Req, Res>, Req>
where Self: Sized,
F: Fn(Self::Response) -> Res { ... }
fn map_err<F, E>(self, f: F) -> ServiceChain<MapErr<Self, F, E>, Req>
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;
async fn call(&self, req: u8, ctx: ServiceCtx<'_, Self>) -> Result<Self::Response, Self::Error> {
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>;Service cannot be called directly, it must be wrapped to an instance of [Pipeline``] or by using ctx` argument of the call method in case of chanined services.
Required Associated Types§
Required Methods§
Sourceasync fn call(
&self,
req: Req,
ctx: ServiceCtx<'_, Self>,
) -> Result<Self::Response, Self::Error>
async fn call( &self, req: Req, ctx: ServiceCtx<'_, Self>, ) -> Result<Self::Response, Self::Error>
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. Caller of the service verifies readiness,
Only way to make a call is to use ctx argument, it enforces readiness before calling
service.
Provided Methods§
Sourceasync fn ready(&self, ctx: ServiceCtx<'_, Self>) -> Result<(), Self::Error>
async fn ready(&self, ctx: ServiceCtx<'_, Self>) -> Result<(), Self::Error>
Returns when the service is able to process requests.
If the service is at capacity, then ready does not returns 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 returns from a ready call and the next invocation of call
results in an error.
Sourcefn poll(&self, cx: &mut Context<'_>) -> Result<(), Self::Error>
fn poll(&self, cx: &mut Context<'_>) -> Result<(), Self::Error>
Polls service from the current task.
Service may require to execute asynchronous computation or maintain asynchronous state.
Sourcefn map<F, Res>(self, f: F) -> ServiceChain<Map<Self, F, Req, Res>, Req>
fn map<F, Res>(self, f: F) -> ServiceChain<Map<Self, F, Req, Res>, Req>
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) -> ServiceChain<MapErr<Self, F, E>, Req>
fn map_err<F, E>(self, f: F) -> ServiceChain<MapErr<Self, F, E>, Req>
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.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.