From: Ben Darnell <ben@bendarnell.com>
Date: Sat, 23 Mar 2019 17:57:41 +0000 (-0400)
Subject: docs: Clarify platform support and add not-on-windows notes
X-Git-Tag: v6.1.0b1~80^2~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a9ba38ff630f142d690b9d1714d2c2e8a3546d98;p=thirdparty%2Ftornado.git

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 43fe3f18b..8cf34f050 100644
--- 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 ac5ac6196..6d2e1d73c 100644
--- 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 c1a5fce7e..cb9e9c996 100644
--- 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 eaf08b2a7..43a77ac4c 100644
--- 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