mirror of
https://github.com/OMGeeky/google-apis-rs.git
synced 2026-01-25 12:44:07 +01:00
288 lines
34 KiB
HTML
288 lines
34 KiB
HTML
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="An asynchronous function from a `Request` to a `Response`."><title>Service in tower_service - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><link rel="stylesheet" href="../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../static.files/rustdoc-ac92e1bbe349e143.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="tower_service" data-themes="" data-resource-suffix="" data-rustdoc-version="1.76.0 (07dca489a 2024-02-04)" data-channel="1.76.0" data-search-js="search-2b6ce74ff89ae146.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../static.files/storage-f2adc0d6ca4d09fb.js"></script><script defer src="sidebar-items.js"></script><script defer src="../static.files/main-305769736d49e732.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-feafe1bb7466e4bd.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-16x16-8b506e7a72182f1c.png"><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc trait"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">☰</button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../tower_service/index.html">tower_service</a><span class="version">0.3.2</span></h2></div><h2 class="location"><a href="#">Service</a></h2><div class="sidebar-elems"><section><h3><a href="#required-associated-types">Required Associated Types</a></h3><ul class="block"><li><a href="#associatedtype.Error">Error</a></li><li><a href="#associatedtype.Future">Future</a></li><li><a href="#associatedtype.Response">Response</a></li></ul><h3><a href="#required-methods">Required Methods</a></h3><ul class="block"><li><a href="#tymethod.call">call</a></li><li><a href="#tymethod.poll_ready">poll_ready</a></li></ul><h3><a href="#foreign-impls">Implementations on Foreign Types</a></h3><ul class="block"><li><a href="#impl-Service%3CRequest%3E-for-%26mut+S">&'a mut S</a></li><li><a href="#impl-Service%3CRequest%3E-for-Box%3CS%3E">Box<S></a></li></ul><h3><a href="#implementors">Implementors</a></h3></section><h2><a href="index.html">In crate tower_service</a></h2></div></nav><div class="sidebar-resizer"></div>
|
||
<main><div class="width-limiter"><nav class="sub"><form class="search-form"><span></span><div id="sidebar-button" tabindex="-1"><a href="../tower_service/all.html" title="show sidebar"></a></div><input class="search-input" name="search" aria-label="Run search in the documentation" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" tabindex="-1"><a href="../help.html" title="help">?</a></div><div id="settings-menu" tabindex="-1"><a href="../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1>Trait <a href="index.html">tower_service</a>::<wbr><a class="trait" href="#">Service</a><button id="copy-path" title="Copy item path to clipboard"><img src="../static.files/clipboard-7571035ce49a181d.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="src" href="../src/tower_service/lib.rs.html#311-355">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>−</span>]</button></span></div><pre class="rust item-decl"><code>pub trait Service<Request> {
|
||
type <a href="#associatedtype.Response" class="associatedtype">Response</a>;
|
||
type <a href="#associatedtype.Error" class="associatedtype">Error</a>;
|
||
type <a href="#associatedtype.Future" class="associatedtype">Future</a>: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/future/future/trait.Future.html" title="trait core::future::future::Future">Future</a><Output = <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a><Self::<a class="associatedtype" href="trait.Service.html#associatedtype.Response" title="type tower_service::Service::Response">Response</a>, Self::<a class="associatedtype" href="trait.Service.html#associatedtype.Error" title="type tower_service::Service::Error">Error</a>>>;
|
||
|
||
// Required methods
|
||
fn <a href="#tymethod.poll_ready" class="fn">poll_ready</a>(
|
||
&mut self,
|
||
cx: &mut <a class="struct" href="https://doc.rust-lang.org/1.76.0/core/task/wake/struct.Context.html" title="struct core::task::wake::Context">Context</a><'_>
|
||
) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/task/poll/enum.Poll.html" title="enum core::task::poll::Poll">Poll</a><<a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.unit.html">()</a>, Self::<a class="associatedtype" href="trait.Service.html#associatedtype.Error" title="type tower_service::Service::Error">Error</a>>>;
|
||
<span class="item-spacer"></span> fn <a href="#tymethod.call" class="fn">call</a>(&mut self, req: Request) -> Self::<a class="associatedtype" href="trait.Service.html#associatedtype.Future" title="type tower_service::Service::Future">Future</a>;
|
||
}</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>An asynchronous function from a <code>Request</code> to a <code>Response</code>.</p>
|
||
<p>The <code>Service</code> trait is a simplified interface making it easy to write
|
||
network applications in a modular and reusable way, decoupled from the
|
||
underlying protocol. It is one of Tower’s fundamental abstractions.</p>
|
||
<h2 id="functional"><a href="#functional">Functional</a></h2>
|
||
<p>A <code>Service</code> is a function of a <code>Request</code>. It immediately returns a
|
||
<code>Future</code> representing the eventual completion of processing the
|
||
request. The actual request processing may happen at any time in the
|
||
future, on any thread or executor. The processing may depend on calling
|
||
other services. At some point in the future, the processing will complete,
|
||
and the <code>Future</code> will resolve to a response or error.</p>
|
||
<p>At a high level, the <code>Service::call</code> function represents an RPC request. The
|
||
<code>Service</code> value can be a server or a client.</p>
|
||
<h2 id="server"><a href="#server">Server</a></h2>
|
||
<p>An RPC server <em>implements</em> the <code>Service</code> trait. Requests received by the
|
||
server over the network are deserialized and then passed as an argument to the
|
||
server value. The returned response is sent back over the network.</p>
|
||
<p>As an example, here is how an HTTP request is processed by a server:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>http::{Request, Response, StatusCode};
|
||
|
||
<span class="kw">struct </span>HelloWorld;
|
||
|
||
<span class="kw">impl </span>Service<Request<Vec<u8>>> <span class="kw">for </span>HelloWorld {
|
||
<span class="kw">type </span>Response = Response<Vec<u8>>;
|
||
<span class="kw">type </span>Error = http::Error;
|
||
<span class="kw">type </span>Future = Pin<Box<<span class="kw">dyn </span>Future<Output = <span class="prelude-ty">Result</span><<span class="self">Self</span>::Response, <span class="self">Self</span>::Error>>>>;
|
||
|
||
<span class="kw">fn </span>poll_ready(<span class="kw-2">&mut </span><span class="self">self</span>, cx: <span class="kw-2">&mut </span>Context<<span class="lifetime">'_</span>>) -> Poll<<span class="prelude-ty">Result</span><(), <span class="self">Self</span>::Error>> {
|
||
Poll::Ready(<span class="prelude-val">Ok</span>(()))
|
||
}
|
||
|
||
<span class="kw">fn </span>call(<span class="kw-2">&mut </span><span class="self">self</span>, req: Request<Vec<u8>>) -> <span class="self">Self</span>::Future {
|
||
<span class="comment">// create the body
|
||
</span><span class="kw">let </span>body: Vec<u8> = <span class="string">"hello, world!\n"
|
||
</span>.as_bytes()
|
||
.to_owned();
|
||
<span class="comment">// Create the HTTP response
|
||
</span><span class="kw">let </span>resp = Response::builder()
|
||
.status(StatusCode::OK)
|
||
.body(body)
|
||
.expect(<span class="string">"Unable to create `http::Response`"</span>);
|
||
|
||
<span class="comment">// create a response in a future.
|
||
</span><span class="kw">let </span>fut = <span class="kw">async </span>{
|
||
<span class="prelude-val">Ok</span>(resp)
|
||
};
|
||
|
||
<span class="comment">// Return the response as an immediate future
|
||
</span>Box::pin(fut)
|
||
}
|
||
}</code></pre></div>
|
||
<h2 id="client"><a href="#client">Client</a></h2>
|
||
<p>A client consumes a service by using a <code>Service</code> value. The client may
|
||
issue requests by invoking <code>call</code> and passing the request as an argument.
|
||
It then receives the response by waiting for the returned future.</p>
|
||
<p>As an example, here is how a Redis request would be issued:</p>
|
||
|
||
<div class="example-wrap ignore"><a href="#" class="tooltip" title="This example is not tested">ⓘ</a><pre class="rust rust-example-rendered"><code><span class="kw">let </span>client = redis::Client::new()
|
||
.connect(<span class="string">"127.0.0.1:6379"</span>.parse().unwrap())
|
||
.unwrap();
|
||
|
||
<span class="kw">let </span>resp = client.call(Cmd::set(<span class="string">"foo"</span>, <span class="string">"this is the value of foo"</span>)).<span class="kw">await</span><span class="question-mark">?</span>;
|
||
|
||
<span class="comment">// Wait for the future to resolve
|
||
</span><span class="macro">println!</span>(<span class="string">"Redis response: {:?}"</span>, resp);</code></pre></div>
|
||
<h2 id="middleware--layer"><a href="#middleware--layer">Middleware / Layer</a></h2>
|
||
<p>More often than not, all the pieces needed for writing robust, scalable
|
||
network applications are the same no matter the underlying protocol. By
|
||
unifying the API for both clients and servers in a protocol agnostic way,
|
||
it is possible to write middleware that provide these pieces in a
|
||
reusable way.</p>
|
||
<p>Take timeouts as an example:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>tower_service::Service;
|
||
<span class="kw">use </span>tower_layer::Layer;
|
||
<span class="kw">use </span>futures::FutureExt;
|
||
<span class="kw">use </span>std::future::Future;
|
||
<span class="kw">use </span>std::task::{Context, Poll};
|
||
<span class="kw">use </span>std::time::Duration;
|
||
<span class="kw">use </span>std::pin::Pin;
|
||
<span class="kw">use </span>std::fmt;
|
||
<span class="kw">use </span>std::error::Error;
|
||
|
||
<span class="comment">// Our timeout service, which wraps another service and
|
||
// adds a timeout to its response future.
|
||
</span><span class="kw">pub struct </span>Timeout<T> {
|
||
inner: T,
|
||
timeout: Duration,
|
||
}
|
||
|
||
<span class="kw">impl</span><T> Timeout<T> {
|
||
<span class="kw">pub fn </span>new(inner: T, timeout: Duration) -> Timeout<T> {
|
||
Timeout {
|
||
inner,
|
||
timeout
|
||
}
|
||
}
|
||
}
|
||
|
||
<span class="comment">// The error returned if processing a request timed out
|
||
</span><span class="attr">#[derive(Debug)]
|
||
</span><span class="kw">pub struct </span>Expired;
|
||
|
||
<span class="kw">impl </span>fmt::Display <span class="kw">for </span>Expired {
|
||
<span class="kw">fn </span>fmt(<span class="kw-2">&</span><span class="self">self</span>, f: <span class="kw-2">&mut </span>fmt::Formatter<<span class="lifetime">'_</span>>) -> fmt::Result {
|
||
<span class="macro">write!</span>(f, <span class="string">"expired"</span>)
|
||
}
|
||
}
|
||
|
||
<span class="kw">impl </span>Error <span class="kw">for </span>Expired {}
|
||
|
||
<span class="comment">// We can implement `Service` for `Timeout<T>` if `T` is a `Service`
|
||
</span><span class="kw">impl</span><T, Request> Service<Request> <span class="kw">for </span>Timeout<T>
|
||
<span class="kw">where
|
||
</span>T: Service<Request>,
|
||
T::Future: <span class="lifetime">'static</span>,
|
||
T::Error: Into<Box<<span class="kw">dyn </span>Error + Send + Sync>> + <span class="lifetime">'static</span>,
|
||
T::Response: <span class="lifetime">'static</span>,
|
||
{
|
||
<span class="comment">// `Timeout` doesn't modify the response type, so we use `T`'s response type
|
||
</span><span class="kw">type </span>Response = T::Response;
|
||
<span class="comment">// Errors may be either `Expired` if the timeout expired, or the inner service's
|
||
// `Error` type. Therefore, we return a boxed `dyn Error + Send + Sync` trait object to erase
|
||
// the error's type.
|
||
</span><span class="kw">type </span>Error = Box<<span class="kw">dyn </span>Error + Send + Sync>;
|
||
<span class="kw">type </span>Future = Pin<Box<<span class="kw">dyn </span>Future<Output = <span class="prelude-ty">Result</span><<span class="self">Self</span>::Response, <span class="self">Self</span>::Error>>>>;
|
||
|
||
<span class="kw">fn </span>poll_ready(<span class="kw-2">&mut </span><span class="self">self</span>, cx: <span class="kw-2">&mut </span>Context<<span class="lifetime">'_</span>>) -> Poll<<span class="prelude-ty">Result</span><(), <span class="self">Self</span>::Error>> {
|
||
<span class="comment">// Our timeout service is ready if the inner service is ready.
|
||
// This is how backpressure can be propagated through a tree of nested services.
|
||
</span><span class="self">self</span>.inner.poll_ready(cx).map_err(Into::into)
|
||
}
|
||
|
||
<span class="kw">fn </span>call(<span class="kw-2">&mut </span><span class="self">self</span>, req: Request) -> <span class="self">Self</span>::Future {
|
||
<span class="comment">// Create a future that completes after `self.timeout`
|
||
</span><span class="kw">let </span>timeout = tokio::time::sleep(<span class="self">self</span>.timeout);
|
||
|
||
<span class="comment">// Call the inner service and get a future that resolves to the response
|
||
</span><span class="kw">let </span>fut = <span class="self">self</span>.inner.call(req);
|
||
|
||
<span class="comment">// Wrap those two futures in another future that completes when either one completes
|
||
//
|
||
// If the inner service is too slow the `sleep` future will complete first
|
||
// And an error will be returned and `fut` will be dropped and not polled again
|
||
//
|
||
// We have to box the errors so the types match
|
||
</span><span class="kw">let </span>f = <span class="kw">async move </span>{
|
||
<span class="macro">tokio::select! </span>{
|
||
res = fut => {
|
||
res.map_err(|err| err.into())
|
||
},
|
||
<span class="kw">_ </span>= timeout => {
|
||
<span class="prelude-val">Err</span>(Box::new(Expired) <span class="kw">as </span>Box<<span class="kw">dyn </span>Error + Send + Sync>)
|
||
},
|
||
}
|
||
};
|
||
|
||
Box::pin(f)
|
||
}
|
||
}
|
||
|
||
<span class="comment">// A layer for wrapping services in `Timeout`
|
||
</span><span class="kw">pub struct </span>TimeoutLayer(Duration);
|
||
|
||
<span class="kw">impl </span>TimeoutLayer {
|
||
<span class="kw">pub fn </span>new(delay: Duration) -> <span class="self">Self </span>{
|
||
TimeoutLayer(delay)
|
||
}
|
||
}
|
||
|
||
<span class="kw">impl</span><S> Layer<S> <span class="kw">for </span>TimeoutLayer {
|
||
<span class="kw">type </span>Service = Timeout<S>;
|
||
|
||
<span class="kw">fn </span>layer(<span class="kw-2">&</span><span class="self">self</span>, service: S) -> Timeout<S> {
|
||
Timeout::new(service, <span class="self">self</span>.<span class="number">0</span>)
|
||
}
|
||
}</code></pre></div>
|
||
<p>The above timeout implementation is decoupled from the underlying protocol
|
||
and is also decoupled from client or server concerns. In other words, the
|
||
same timeout middleware could be used in either a client or a server.</p>
|
||
<h2 id="backpressure"><a href="#backpressure">Backpressure</a></h2>
|
||
<p>Calling a <code>Service</code> which is at capacity (i.e., it is temporarily unable to process a
|
||
request) should result in an error. The caller is responsible for ensuring
|
||
that the service is ready to receive the request before calling it.</p>
|
||
<p><code>Service</code> provides a mechanism by which the caller is able to coordinate
|
||
readiness. <code>Service::poll_ready</code> returns <code>Ready</code> if the service expects that
|
||
it is able to process a request.</p>
|
||
<h2 id="be-careful-when-cloning-inner-services"><a href="#be-careful-when-cloning-inner-services">Be careful when cloning inner services</a></h2>
|
||
<p>Services are permitted to panic if <code>call</code> is invoked without obtaining <code>Poll::Ready(Ok(()))</code>
|
||
from <code>poll_ready</code>. You should therefore be careful when cloning services for example to move
|
||
them into boxed futures. Even though the original service is ready, the clone might not be.</p>
|
||
<p>Therefore this kind of code is wrong and might panic:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">struct </span>Wrapper<S> {
|
||
inner: S,
|
||
}
|
||
|
||
<span class="kw">impl</span><R, S> Service<R> <span class="kw">for </span>Wrapper<S>
|
||
<span class="kw">where
|
||
</span>S: Service<R> + Clone + <span class="lifetime">'static</span>,
|
||
R: <span class="lifetime">'static</span>,
|
||
{
|
||
<span class="kw">type </span>Response = S::Response;
|
||
<span class="kw">type </span>Error = S::Error;
|
||
<span class="kw">type </span>Future = Pin<Box<<span class="kw">dyn </span>Future<Output = <span class="prelude-ty">Result</span><<span class="self">Self</span>::Response, <span class="self">Self</span>::Error>>>>;
|
||
|
||
<span class="kw">fn </span>poll_ready(<span class="kw-2">&mut </span><span class="self">self</span>, cx: <span class="kw-2">&mut </span>Context<<span class="lifetime">'_</span>>) -> Poll<<span class="prelude-ty">Result</span><(), <span class="self">Self</span>::Error>> {
|
||
Poll::Ready(<span class="prelude-val">Ok</span>(()))
|
||
}
|
||
|
||
<span class="kw">fn </span>call(<span class="kw-2">&mut </span><span class="self">self</span>, req: R) -> <span class="self">Self</span>::Future {
|
||
<span class="kw">let </span><span class="kw-2">mut </span>inner = <span class="self">self</span>.inner.clone();
|
||
Box::pin(<span class="kw">async move </span>{
|
||
<span class="comment">// `inner` might not be ready since its a clone
|
||
</span>inner.call(req).<span class="kw">await
|
||
</span>})
|
||
}
|
||
}</code></pre></div>
|
||
<p>You should instead use <a href="https://doc.rust-lang.org/1.76.0/core/mem/fn.replace.html" title="fn core::mem::replace"><code>std::mem::replace</code></a> to take the service that was ready:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">struct </span>Wrapper<S> {
|
||
inner: S,
|
||
}
|
||
|
||
<span class="kw">impl</span><R, S> Service<R> <span class="kw">for </span>Wrapper<S>
|
||
<span class="kw">where
|
||
</span>S: Service<R> + Clone + <span class="lifetime">'static</span>,
|
||
R: <span class="lifetime">'static</span>,
|
||
{
|
||
<span class="kw">type </span>Response = S::Response;
|
||
<span class="kw">type </span>Error = S::Error;
|
||
<span class="kw">type </span>Future = Pin<Box<<span class="kw">dyn </span>Future<Output = <span class="prelude-ty">Result</span><<span class="self">Self</span>::Response, <span class="self">Self</span>::Error>>>>;
|
||
|
||
<span class="kw">fn </span>poll_ready(<span class="kw-2">&mut </span><span class="self">self</span>, cx: <span class="kw-2">&mut </span>Context<<span class="lifetime">'_</span>>) -> Poll<<span class="prelude-ty">Result</span><(), <span class="self">Self</span>::Error>> {
|
||
Poll::Ready(<span class="prelude-val">Ok</span>(()))
|
||
}
|
||
|
||
<span class="kw">fn </span>call(<span class="kw-2">&mut </span><span class="self">self</span>, req: R) -> <span class="self">Self</span>::Future {
|
||
<span class="kw">let </span>clone = <span class="self">self</span>.inner.clone();
|
||
<span class="comment">// take the service that was ready
|
||
</span><span class="kw">let </span><span class="kw-2">mut </span>inner = std::mem::replace(<span class="kw-2">&mut </span><span class="self">self</span>.inner, clone);
|
||
Box::pin(<span class="kw">async move </span>{
|
||
inner.call(req).<span class="kw">await
|
||
</span>})
|
||
}
|
||
}</code></pre></div>
|
||
</div></details><h2 id="required-associated-types" class="section-header">Required Associated Types<a href="#required-associated-types" class="anchor">§</a></h2><div class="methods"><details class="toggle" open><summary><section id="associatedtype.Response" class="method"><a class="src rightside" href="../src/tower_service/lib.rs.html#313">source</a><h4 class="code-header">type <a href="#associatedtype.Response" class="associatedtype">Response</a></h4></section></summary><div class="docblock"><p>Responses given by the service.</p>
|
||
</div></details><details class="toggle" open><summary><section id="associatedtype.Error" class="method"><a class="src rightside" href="../src/tower_service/lib.rs.html#316">source</a><h4 class="code-header">type <a href="#associatedtype.Error" class="associatedtype">Error</a></h4></section></summary><div class="docblock"><p>Errors produced by the service.</p>
|
||
</div></details><details class="toggle" open><summary><section id="associatedtype.Future" class="method"><a class="src rightside" href="../src/tower_service/lib.rs.html#319">source</a><h4 class="code-header">type <a href="#associatedtype.Future" class="associatedtype">Future</a>: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/future/future/trait.Future.html" title="trait core::future::future::Future">Future</a><Output = <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a><Self::<a class="associatedtype" href="trait.Service.html#associatedtype.Response" title="type tower_service::Service::Response">Response</a>, Self::<a class="associatedtype" href="trait.Service.html#associatedtype.Error" title="type tower_service::Service::Error">Error</a>>></h4></section></summary><div class="docblock"><p>The future response value.</p>
|
||
</div></details></div><h2 id="required-methods" class="section-header">Required Methods<a href="#required-methods" class="anchor">§</a></h2><div class="methods"><details class="toggle method-toggle" open><summary><section id="tymethod.poll_ready" class="method"><a class="src rightside" href="../src/tower_service/lib.rs.html#340">source</a><h4 class="code-header">fn <a href="#tymethod.poll_ready" class="fn">poll_ready</a>(&mut self, cx: &mut <a class="struct" href="https://doc.rust-lang.org/1.76.0/core/task/wake/struct.Context.html" title="struct core::task::wake::Context">Context</a><'_>) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/task/poll/enum.Poll.html" title="enum core::task::poll::Poll">Poll</a><<a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.unit.html">()</a>, Self::<a class="associatedtype" href="trait.Service.html#associatedtype.Error" title="type tower_service::Service::Error">Error</a>>></h4></section></summary><div class="docblock"><p>Returns <code>Poll::Ready(Ok(()))</code> when the service is able to process requests.</p>
|
||
<p>If the service is at capacity, then <code>Poll::Pending</code> is returned and the task
|
||
is notified when the service becomes ready again. This function is
|
||
expected to be called while on a task. Generally, this can be done with
|
||
a simple <code>futures::future::poll_fn</code> call.</p>
|
||
<p>If <code>Poll::Ready(Err(_))</code> is returned, the service is no longer able to service requests
|
||
and the caller should discard the service instance.</p>
|
||
<p>Once <code>poll_ready</code> returns <code>Poll::Ready(Ok(()))</code>, a request may be dispatched to the
|
||
service using <code>call</code>. Until a request is dispatched, repeated calls to
|
||
<code>poll_ready</code> must return either <code>Poll::Ready(Ok(()))</code> or <code>Poll::Ready(Err(_))</code>.</p>
|
||
<p>Note that <code>poll_ready</code> may reserve shared resources that are consumed in a subsequent
|
||
invocation of <code>call</code>. Thus, it is critical for implementations to not assume that <code>call</code>
|
||
will always be invoked and to ensure that such resources are released if the service is
|
||
dropped before <code>call</code> is invoked or the future returned by <code>call</code> is dropped before it
|
||
is polled.</p>
|
||
</div></details><details class="toggle method-toggle" open><summary><section id="tymethod.call" class="method"><a class="src rightside" href="../src/tower_service/lib.rs.html#354">source</a><h4 class="code-header">fn <a href="#tymethod.call" class="fn">call</a>(&mut self, req: Request) -> Self::<a class="associatedtype" href="trait.Service.html#associatedtype.Future" title="type tower_service::Service::Future">Future</a></h4></section></summary><div class="docblock"><p>Process the request and return the response asynchronously.</p>
|
||
<p>This function is expected to be callable off task. As such,
|
||
implementations should take care to not call <code>poll_ready</code>.</p>
|
||
<p>Before dispatching a request, <code>poll_ready</code> must be called and return
|
||
<code>Poll::Ready(Ok(()))</code>.</p>
|
||
<h5 id="panics"><a href="#panics">Panics</a></h5>
|
||
<p>Implementations are permitted to panic if <code>call</code> is invoked without
|
||
obtaining <code>Poll::Ready(Ok(()))</code> from <code>poll_ready</code>.</p>
|
||
</div></details></div><h2 id="foreign-impls" class="section-header">Implementations on Foreign Types<a href="#foreign-impls" class="anchor">§</a></h2><details class="toggle implementors-toggle"><summary><section id="impl-Service%3CRequest%3E-for-%26mut+S" class="impl"><a class="src rightside" href="../src/tower_service/lib.rs.html#357-372">source</a><a href="#impl-Service%3CRequest%3E-for-%26mut+S" class="anchor">§</a><h3 class="code-header">impl<'a, S, Request> <a class="trait" href="trait.Service.html" title="trait tower_service::Service">Service</a><Request> for <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.reference.html">&'a mut S</a><div class="where">where
|
||
S: <a class="trait" href="trait.Service.html" title="trait tower_service::Service">Service</a><Request> + 'a,</div></h3></section></summary><div class="impl-items"><section id="associatedtype.Response-1" class="associatedtype trait-impl"><a href="#associatedtype.Response-1" class="anchor">§</a><h4 class="code-header">type <a href="#associatedtype.Response" class="associatedtype">Response</a> = <S as <a class="trait" href="trait.Service.html" title="trait tower_service::Service">Service</a><Request>>::<a class="associatedtype" href="trait.Service.html#associatedtype.Response" title="type tower_service::Service::Response">Response</a></h4></section><section id="associatedtype.Error-1" class="associatedtype trait-impl"><a href="#associatedtype.Error-1" class="anchor">§</a><h4 class="code-header">type <a href="#associatedtype.Error" class="associatedtype">Error</a> = <S as <a class="trait" href="trait.Service.html" title="trait tower_service::Service">Service</a><Request>>::<a class="associatedtype" href="trait.Service.html#associatedtype.Error" title="type tower_service::Service::Error">Error</a></h4></section><section id="associatedtype.Future-1" class="associatedtype trait-impl"><a href="#associatedtype.Future-1" class="anchor">§</a><h4 class="code-header">type <a href="#associatedtype.Future" class="associatedtype">Future</a> = <S as <a class="trait" href="trait.Service.html" title="trait tower_service::Service">Service</a><Request>>::<a class="associatedtype" href="trait.Service.html#associatedtype.Future" title="type tower_service::Service::Future">Future</a></h4></section><section id="method.poll_ready" class="method trait-impl"><a class="src rightside" href="../src/tower_service/lib.rs.html#365-367">source</a><a href="#method.poll_ready" class="anchor">§</a><h4 class="code-header">fn <a href="#tymethod.poll_ready" class="fn">poll_ready</a>(&mut self, cx: &mut <a class="struct" href="https://doc.rust-lang.org/1.76.0/core/task/wake/struct.Context.html" title="struct core::task::wake::Context">Context</a><'_>) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/task/poll/enum.Poll.html" title="enum core::task::poll::Poll">Poll</a><<a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.unit.html">()</a>, S::<a class="associatedtype" href="trait.Service.html#associatedtype.Error" title="type tower_service::Service::Error">Error</a>>></h4></section><section id="method.call" class="method trait-impl"><a class="src rightside" href="../src/tower_service/lib.rs.html#369-371">source</a><a href="#method.call" class="anchor">§</a><h4 class="code-header">fn <a href="#tymethod.call" class="fn">call</a>(&mut self, request: Request) -> S::<a class="associatedtype" href="trait.Service.html#associatedtype.Future" title="type tower_service::Service::Future">Future</a></h4></section></div></details><details class="toggle implementors-toggle"><summary><section id="impl-Service%3CRequest%3E-for-Box%3CS%3E" class="impl"><a class="src rightside" href="../src/tower_service/lib.rs.html#374-389">source</a><a href="#impl-Service%3CRequest%3E-for-Box%3CS%3E" class="anchor">§</a><h3 class="code-header">impl<S, Request> <a class="trait" href="trait.Service.html" title="trait tower_service::Service">Service</a><Request> for <a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/boxed/struct.Box.html" title="struct alloc::boxed::Box">Box</a><S><div class="where">where
|
||
S: <a class="trait" href="trait.Service.html" title="trait tower_service::Service">Service</a><Request> + ?<a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h3></section></summary><div class="impl-items"><section id="associatedtype.Response-2" class="associatedtype trait-impl"><a href="#associatedtype.Response-2" class="anchor">§</a><h4 class="code-header">type <a href="#associatedtype.Response" class="associatedtype">Response</a> = <S as <a class="trait" href="trait.Service.html" title="trait tower_service::Service">Service</a><Request>>::<a class="associatedtype" href="trait.Service.html#associatedtype.Response" title="type tower_service::Service::Response">Response</a></h4></section><section id="associatedtype.Error-2" class="associatedtype trait-impl"><a href="#associatedtype.Error-2" class="anchor">§</a><h4 class="code-header">type <a href="#associatedtype.Error" class="associatedtype">Error</a> = <S as <a class="trait" href="trait.Service.html" title="trait tower_service::Service">Service</a><Request>>::<a class="associatedtype" href="trait.Service.html#associatedtype.Error" title="type tower_service::Service::Error">Error</a></h4></section><section id="associatedtype.Future-2" class="associatedtype trait-impl"><a href="#associatedtype.Future-2" class="anchor">§</a><h4 class="code-header">type <a href="#associatedtype.Future" class="associatedtype">Future</a> = <S as <a class="trait" href="trait.Service.html" title="trait tower_service::Service">Service</a><Request>>::<a class="associatedtype" href="trait.Service.html#associatedtype.Future" title="type tower_service::Service::Future">Future</a></h4></section><section id="method.poll_ready-1" class="method trait-impl"><a class="src rightside" href="../src/tower_service/lib.rs.html#382-384">source</a><a href="#method.poll_ready-1" class="anchor">§</a><h4 class="code-header">fn <a href="#tymethod.poll_ready" class="fn">poll_ready</a>(&mut self, cx: &mut <a class="struct" href="https://doc.rust-lang.org/1.76.0/core/task/wake/struct.Context.html" title="struct core::task::wake::Context">Context</a><'_>) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/task/poll/enum.Poll.html" title="enum core::task::poll::Poll">Poll</a><<a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.unit.html">()</a>, S::<a class="associatedtype" href="trait.Service.html#associatedtype.Error" title="type tower_service::Service::Error">Error</a>>></h4></section><section id="method.call-1" class="method trait-impl"><a class="src rightside" href="../src/tower_service/lib.rs.html#386-388">source</a><a href="#method.call-1" class="anchor">§</a><h4 class="code-header">fn <a href="#tymethod.call" class="fn">call</a>(&mut self, request: Request) -> S::<a class="associatedtype" href="trait.Service.html#associatedtype.Future" title="type tower_service::Service::Future">Future</a></h4></section></div></details><h2 id="implementors" class="section-header">Implementors<a href="#implementors" class="anchor">§</a></h2><div id="implementors-list"></div><script src="../trait.impl/tower_service/trait.Service.js" data-ignore-extern-crates="alloc" async></script></section></div></main></body></html> |