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 from a Request to a Response.
The Service trait represents a request/response interaction, receiving
requests and returning replies. Conceptually, a service is like a function
with one argument that returns a result asynchronously:
async fn(Request) -> Result<Response, Error>The Service trait generalizes this form. Requests are defined as a generic
type parameter, while responses and other details are defined as associated
types on the trait implementation. This design allows services to accept
many request types and produce a single response type.
Services can also have internal mutable state that influences computation
using Cell, RefCell, or Mutex. Services intentionally do not take
&mut self to reduce overhead in common use cases.
Service provides a uniform API; the same abstractions can represent both
clients and servers. Services describe only transformation operations,
which encourages simple API surfaces, easier testing, and straightforward
composition.
Services can only be called within a pipeline. The Pipeline enforces
shared readiness for all services in the pipeline. To process requests from
one service to another, all services must be ready; otherwise, processing
is paused until that state is achieved.
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>
Processes a request and returns the response asynchronously.
The call method can only be invoked within a pipeline, which enforces
readiness for all services in the pipeline. Implementations of call
must not call ready; the ctx argument ensures the service is ready
before it is invoked.
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 ready to process requests.
If the service is at capacity, ready will not return immediately. The current
task is notified when the service becomes ready again. This function should
be called while executing on a task.
Note: Pipeline readiness is maintained across all services in the pipeline. The pipeline can process requests only if every service in the pipeline is ready.
Sourceasync fn shutdown(&self)
async fn shutdown(&self)
Shuts down the service.
Returns when the service has been properly shut down.
Sourcefn poll(&self, cx: &mut Context<'_>) -> Result<(), Self::Error>
fn poll(&self, cx: &mut Context<'_>) -> Result<(), Self::Error>
Polls the service from the current async task.
The service may perform asynchronous computations or maintain asynchronous state during polling.
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>
Maps this service’s output to a different type, returning a new service.
This is similar to Option::map or Iterator::map, changing the
output type of the underlying service.
This function consumes the original service and returns a wrapped version,
following the pattern of standard library map methods.
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>
Maps this service’s error to a different type, returning a new service.
This is similar to Result::map_err, changing the error type of the
underlying service. It is useful, for example, to ensure multiple
services have the same error type.
This function consumes the original service and returns a wrapped version.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".