Correct misleading guidance on multiprocessing

Link the connections intro to the dedicated section
on multiprocessing rather than stating that a separate
engine per process is needed, since this is inaccurate
and vague.

Change-Id: I48c66f88a90db918e864cd198c6aed335e28c7e6

diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst
index 5619377de8c630e8fb29df85e5942d1574cfd33b..42806d53974fc1866eb79564ca24c743541cb6a1 100644 (file)
--- a/doc/build/core/connections.rst
+++ b/doc/build/core/connections.rst
@@ -32,14 +32,12 @@ which represents just one connection resource - the :class:`.Engine` is most
 efficient when created just once at the module level of an application, not
 per-object or per-function call.
 
-For a multiple-process application that uses the ``os.fork`` system call, or
-for example the Python ``multiprocessing`` module, it's usually required that a
-separate :class:`.Engine` be used for each child process. This is because the
-:class:`.Engine` maintains a reference to a connection pool that ultimately
-references DBAPI connections - these tend to not be portable across process
-boundaries. An :class:`.Engine` that is configured not to use pooling (which
-is achieved via the usage of :class:`.NullPool`) does not have this
-requirement.
+.. sidebar:: tip
+
+    When using an :class:`.Engine` with multiple Python processes, such as when
+    using ``os.fork`` or Python ``multiprocessing``, it's important that the
+    engine is initialized per process.  See :ref:`pooling_multiprocessing` for
+    details.
 
 The engine can be used directly to issue SQL to the database. The most generic
 way is first procure a connection resource, which you get via the

diff --git a/doc/build/core/pooling.rst b/doc/build/core/pooling.rst
index ebd396fc54afe37e76ca60638ee3fb8bbfb9a72f..94064ffc5588a6305b27038aaaa86110bd5d9865 100644 (file)
--- a/doc/build/core/pooling.rst
+++ b/doc/build/core/pooling.rst
@@ -430,6 +430,7 @@ Note that the flag only applies to :class:`.QueuePool` use.
     :ref:`pool_disconnects`
 
 
+.. _pooling_multiprocessing:
 
 Using Connection Pools with Multiprocessing
 -------------------------------------------