From 491333858c46fae8c7f8d0ee6dec1be7c81b83da Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Fri, 20 Mar 2020 11:17:47 -0400 Subject: [PATCH] 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 --- doc/build/core/connections.rst | 14 ++++++-------- doc/build/core/pooling.rst | 1 + 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 5619377de8..42806d5397 100644 --- 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 ebd396fc54..94064ffc55 100644 --- 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 ------------------------------------------- -- 2.39.5