9bae225918
This patch adds the `DirectService` trait, and related implementations over it in `tower_balance` and `tower_buffer`. `DirectService` is similar to a `Service`, but must be "driven" through calls to `poll_service` for the futures returned by `call` to make progress. The motivation behind adding this trait is that many current `Service` implementations spawn long-running futures when the service is created, which then drive the work necessary to turn requests into responses. A simple example of this is a service that writes requests over a `TcpStream` and reads responses over that same `TcpStream`. The underlying stream must be read from to discover new responses, but there is no single entity to drive that task. The returned futures would share access to the stream (and worse yet, may get responses out of order), and then service itself is not guaranteed to see any more calls to it as the client is waiting for its requests to finish. `DirectService` solves this by introducing a new method, `poll_service`, which must be called to make progress on in-progress futures. Furthermore, like `Future::poll`, `poll_service` must be called whenever the associated task is notified so that the service can also respect time-based operations like heartbeats. The PR includes changes to both `tower_balance::Balance` and `tower_buffer::Buffer` to add support for wrapping `DirectService`s. For `Balance` this is straightforward: if the inner service is a `Service`, the `Balance` also implements `Service`; if the inner service is a `DirectService`, the `Balance` is itself also a `DirectService`. For `Buffer`, this is more involved, as a `Buffer` turns any `DirectService` *into* a `Service`. The `Buffer`'s `Worker` is spawned, and will therefore drive the wrapped `DirectService`. One complication arises in that `Buffer<T>` requires that `T: Service`, but you can safely construct a `Buffer` over a `DirectService` per the above. `Buffer` works around this by exposing ```rust impl Service for HandleTo<S> where S: DirectService {} ``` And giving out `Buffer<HandleTo<S>>` when the `new_directed(s: S)` constructor is invoked. Since `Buffer` never calls any methods on the service it wraps, `HandleTo`'s implementation just consists of calls to `unreachable!()`. Note that `tower_buffer` now also includes a `DirectedService` type, which is a wrapper around a `Service` that implements `DirectService`. In theory, we could do away with this by adding a blanket impl: ```rust impl<T> DirectedService for T where T: Service {} ``` but until we have specialization, this would prevent downstream users from implementing `DirectService` themselves. Finally, this also makes `Buffer` use a bounded mpsc channel, which introduces a new capacity argument to `Buffer::new`. Fixes #110. |
||
---|---|---|
.. | ||
src | ||
Cargo.toml | ||
LICENSE | ||
README.md |
README.md
Tower Service
The foundational Service
trait that Tower is based on.
Overview
The Service
trait provides the foundation upon which Tower is built. It is a
simple, but powerful trait. At its heart, Service
is just an asynchronous
function of request to response.
fn(Request) -> Future<Item = Response>
Implementations of Service
take a request, the type of which varies per
protocol, and returns a future representing the eventual completion or failure
of the response.
Services are used to represent both clients and servers. An instance of
Service
is used through a client; a server implements Service
.
By using standardizing the interface, middleware can be created. Middleware
implement Service
by passing the request to another Service
. The
middleware may take actions such as modify the request.
License
This project is licensed under the MIT license.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tower by you, shall be licensed as MIT, without any additional terms or conditions.