From 2a74b91181846002e7e3a5482b602b6019635c34 Mon Sep 17 00:00:00 2001 From: Sean McArthur Date: Tue, 30 Jan 2018 13:18:51 -0800 Subject: [PATCH] docs(server): deprecated bind_connection, note about Connection's Opaque item --- src/server/mod.rs | 10 ++++++++++ src/server/server_proto.rs | 13 +++---------- 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/src/server/mod.rs b/src/server/mod.rs index cbec7264..c9fb1538 100644 --- a/src/server/mod.rs +++ b/src/server/mod.rs @@ -105,6 +105,16 @@ pub struct AddrIncoming { /// A future binding a connection with a Service. /// /// Polling this future will drive HTTP forward. +/// +/// # Note +/// +/// This will currently yield an unnameable (`Opaque`) value +/// on success. The purpose of this is that nothing can be assumed about +/// the type, not even it's name. It's probable that in a later release, +/// this future yields the underlying IO object, which could be done without +/// a breaking change. +/// +/// It is likely best to just map the value to `()`, for now. #[must_use = "futures do nothing unless polled"] pub struct Connection where diff --git a/src/server/server_proto.rs b/src/server/server_proto.rs index 28563e19..484f8ecf 100644 --- a/src/server/server_proto.rs +++ b/src/server/server_proto.rs @@ -30,17 +30,10 @@ impl + 'static> Http { /// Use this `Http` instance to create a new server task which handles the /// connection `io` provided. /// - /// This is the low-level method used to actually spawn handling a TCP - /// connection, typically. The `handle` provided is the event loop on which - /// the server task will be spawned, `io` is the I/O object associated with - /// this connection (data that's read/written), `remote_addr` is the remote - /// peer address of the HTTP client, and `service` defines how HTTP requests - /// will be handled (and mapped to responses). + /// # Deprecated /// - /// This method is typically not invoked directly but is rather transitively - /// used through [`bind`](#method.bind). This can be useful, - /// however, when writing mocks or accepting sockets from a non-TCP - /// location. + /// This method is deprecated. If seeking a replacement, consider + /// `Http::serve_connection`. pub fn bind_connection(&self, handle: &Handle, io: I,