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
(cherry picked from commit 491333858c46fae8c7f8d0ee6dec1be7c81b83da)

diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst
index f60583866017fb05cd5363514d39a52eb633c11f..7575982c9ed83e1e46540ca3a3e93ba959d8cf52 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 181ab6b540b167079d208b99ea6bda07a14da93e..02e3be41c1e2d1b72f3f533eb0970b229994b2b2 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
 -------------------------------------------