docs: Clarify platform support and add not-on-windows notes

We also picked up solaris /dev/poll support with the move to asyncio.

See #2622

diff --git a/docs/guide/running.rst b/docs/guide/running.rst
index 43fe3f18b1c0ee2d5311a272b16e7d414a42af0c..8cf34f05024c0fd36d4d69708de3864be7ba3320 100644 (file)
--- a/docs/guide/running.rst
+++ b/docs/guide/running.rst
@@ -34,8 +34,9 @@ multiple Python processes to take full advantage of multi-CPU machines.
 Typically it is best to run one process per CPU.
 
 Tornado includes a built-in multi-process mode to start several
-processes at once.  This requires a slight alteration to the standard
-main function:
+processes at once (note that multi-process mode does not work on
+Windows). This requires a slight alteration to the standard main
+function:
 
 .. testcode::
 

diff --git a/docs/index.rst b/docs/index.rst
index ac5ac61966a89ea4b728cceadd2a32aad7ad0e73..6d2e1d73c25ab75047cf19744603312bc6763d7b 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -109,16 +109,16 @@ packages may be useful:
   non-blocking DNS resolver that can be used when threads are not
   appropriate.
 
-**Platforms**: Tornado should run on any Unix-like platform, although
-for the best performance and scalability only Linux (with ``epoll``)
-and BSD (with ``kqueue``) are recommended for production deployment
-(even though Mac OS X is derived from BSD and supports kqueue, its
-networking performance is generally poor so it is recommended only for
-development use).  Tornado will also run on Windows, although this
-configuration is not officially supported and is recommended only for
-development use. Without reworking Tornado IOLoop interface, it's not
-possible to add a native Tornado Windows IOLoop implementation or
-leverage Windows' IOCP support from frameworks like AsyncIO or Twisted.
+**Platforms**: Tornado is designed for Unix-like platforms, with best
+performance and scalability on systems supporting ``epoll`` (Linux),
+``kqueue`` (BSD/macOS), or ``/dev/poll`` (Solaris).
+
+Tornado will also run on Windows, although this configuration is not
+officially supported or recommended for production use. Some features
+are missing on Windows (including multi-process mode) and scalability
+is limited (Even though Tornado is built on ``asyncio``, which
+supports Windows, Tornado does not use the APIs that are necessary for
+scalable networking on Windows).
 
 Documentation
 -------------

diff --git a/tornado/process.py b/tornado/process.py
index c1a5fce7ec486624b5f1e86e73a8fcceb9bd1727..cb9e9c996f69fd68e034e9b5717ab60967257cc3 100644 (file)
--- a/tornado/process.py
+++ b/tornado/process.py
@@ -115,6 +115,8 @@ def fork_processes(num_processes: Optional[int], max_restarts: int = None) -> in
     exception.
 
     max_restarts defaults to 100.
+
+    Availability: Unix
     """
     if max_restarts is None:
         max_restarts = 100
@@ -273,6 +275,8 @@ class Subprocess(object):
         In many cases a close callback on the stdout or stderr streams
         can be used as an alternative to an exit callback if the
         signal handler is causing a problem.
+
+        Availability: Unix
         """
         self._exit_callback = callback
         Subprocess.initialize()
@@ -294,6 +298,8 @@ class Subprocess(object):
         to suppress this behavior and return the exit status without raising.
 
         .. versionadded:: 4.2
+
+        Availability: Unix
         """
         future = Future()  # type: Future[int]
 
@@ -321,6 +327,8 @@ class Subprocess(object):
         .. versionchanged:: 5.0
            The ``io_loop`` argument (deprecated since version 4.1) has been
            removed.
+
+        Availability: Unix
         """
         if cls._initialized:
             return

diff --git a/tornado/tcpserver.py b/tornado/tcpserver.py
index eaf08b2a7b4651fff66188a8d7fd1cc2ad88e76b..43a77ac4c56793e5f8594c7e3e54cea06518e726 100644 (file)
--- a/tornado/tcpserver.py
+++ b/tornado/tcpserver.py
@@ -229,6 +229,8 @@ class TCPServer(object):
         When using multiple processes, no IOLoops can be created or
         referenced until after the call to ``TCPServer.start(n)``.
 
+        Values of ``num_processes`` other than 1 are not supported on Windows.
+
         The ``max_restarts`` argument is passed to `.fork_processes`.
 
         .. versionchanged:: 6.0