diff --git a/tokio-reactor/src/lib.rs b/tokio-reactor/src/lib.rs index 1a1b8b3f1..74a14f704 100644 --- a/tokio-reactor/src/lib.rs +++ b/tokio-reactor/src/lib.rs @@ -94,6 +94,9 @@ pub struct Reactor { /// A `Handle` is used for associating I/O objects with an event loop /// explicitly. Typically though you won't end up using a `Handle` that often /// and will instead use the default reactor for the execution context. +/// +/// By default, most components bind lazily to reactors. +/// To get this behavior when manually passing a `Handle`, use `default()`. #[derive(Clone)] pub struct Handle { inner: Option, @@ -475,6 +478,7 @@ impl Unpark for Handle { } impl Default for Handle { + /// Returns a "default" handle, i.e., a handle that lazily binds to a reactor. fn default() -> Handle { Handle { inner: None } } diff --git a/tokio-tcp/src/listener.rs b/tokio-tcp/src/listener.rs index e96b7f06d..e6f8ce3ed 100644 --- a/tokio-tcp/src/listener.rs +++ b/tokio-tcp/src/listener.rs @@ -159,6 +159,7 @@ impl TcpListener { /// /// Finally, the `handle` argument is the event loop that this listener will /// be bound to. + /// Use `Handle::default()` to lazily bind to an event loop, just like `bind` does. /// /// The platform specific behavior of this function looks like: /// diff --git a/tokio-tcp/src/stream.rs b/tokio-tcp/src/stream.rs index 4f39feab5..0a62804b1 100644 --- a/tokio-tcp/src/stream.rs +++ b/tokio-tcp/src/stream.rs @@ -69,8 +69,7 @@ impl TcpStream { /// /// This function will convert a TCP stream created by the standard library /// to a TCP stream ready to be used with the provided event loop handle. - /// The stream returned is associated with the event loop and ready to - /// perform I/O. + /// Use `Handle::default()` to lazily bind to an event loop, just like `connect` does. pub fn from_std(stream: net::TcpStream, handle: &Handle) -> io::Result { diff --git a/tokio-udp/src/socket.rs b/tokio-udp/src/socket.rs index d671d255a..0d0ea220d 100644 --- a/tokio-udp/src/socket.rs +++ b/tokio-udp/src/socket.rs @@ -36,6 +36,8 @@ impl UdpSocket { /// This can be used in conjunction with net2's `UdpBuilder` interface to /// configure a socket before it's handed off, such as setting options like /// `reuse_address` or binding to multiple addresses. + /// + /// Use `Handle::default()` to lazily bind to an event loop, just like `bind` does. pub fn from_std(socket: net::UdpSocket, handle: &Handle) -> io::Result { let io = mio::net::UdpSocket::from_socket(socket)?;