Document that IOStream.connect blocks on DNS and recommend TCPClient instead.

Closes #861.

diff --git a/tornado/iostream.py b/tornado/iostream.py
index 7aa268e5ca49941278268d05d9e7a259ede257c6..8b6142582a9ff73275ab6f31b2ec50858b1364f4 100644 (file)
--- a/tornado/iostream.py
+++ b/tornado/iostream.py
@@ -950,11 +950,19 @@ class IOStream(BaseIOStream):
 
         May only be called if the socket passed to the constructor was
         not previously connected.  The address parameter is in the
-        same format as for `socket.connect <socket.socket.connect>`,
-        i.e. a ``(host, port)`` tuple.  If ``callback`` is specified,
-        it will be called with no arguments when the connection is
-        completed; if not this method returns a `.Future` (whose result
-        after a successful connection will be the stream itself).
+        same format as for `socket.connect <socket.socket.connect>` for
+        the type of socket passed to the IOStream constructor,
+        e.g. an ``(ip, port)`` tuple.  Hostnames are accepted here,
+        but will be resolved synchronously and block the IOLoop.
+        If you have a hostname instead of an IP address, the `.TCPClient`
+        class is recommended instead of calling this method directly.
+        `.TCPClient` will do asynchronous DNS resolution and handle
+        both IPv4 and IPv6.
+
+        If ``callback`` is specified, it will be called with no
+        arguments when the connection is completed; if not this method
+        returns a `.Future` (whose result after a successful
+        connection will be the stream itself).
 
         If specified, the ``server_hostname`` parameter will be used
         in SSL connections for certificate validation (if requested in
@@ -969,6 +977,7 @@ class IOStream(BaseIOStream):
 
         .. versionchanged:: 4.0
             If no callback is given, returns a `.Future`.
+
         """
         self._connecting = True
         try: