further simplify pool-sharing doc

1. the event based approach doesn't require dispose() to be
   called at all, and the note that the "pool will hang" makes
   no sense.   I have no idea what that refers towards
2. the subsequent paragraph about connections and sessions
   is unintelligible.  old paragraphs like these are likely
   why people complain about the docs so much.  try to just
   say "don't do this", as that is easier than trying to
   explain to use connection.invalidate() etc.

Change-Id: Id840c65a2f71583ced4dc82fd8690e7da4c4b10e
(cherry picked from commit b098d2a8b9c8a6fd1ddc5dce1eca7e70ace3f545)

diff --git a/doc/build/core/pooling.rst b/doc/build/core/pooling.rst
index 7f490d799134a32eff7cc9c8ce7db79366e225b7..486cbe4162d9aa2fe472defda7ac82accd66673f 100644 (file)
--- a/doc/build/core/pooling.rst
+++ b/doc/build/core/pooling.rst
@@ -487,9 +487,7 @@ are three general approaches to this:
     # engine.dispose() first
 
 4. An event handler can be applied to the connection pool that tests for
-   connections being shared across process boundaries, and invalidates them.
-   This approach, **when combined with an explicit call to dispose() as
-   mentioned above in options 2 or 3**, should cover all cases::
+   connections being shared across process boundaries, and invalidates them::
 
     from sqlalchemy import event
     from sqlalchemy import exc
@@ -517,22 +515,15 @@ are three general approaches to this:
    originated in a different parent process as an "invalid" connection,
    coercing the pool to recycle the connection record to make a new connection.
 
-   When using the above recipe, **ensure the dispose approach from #2 is also
-   used**, as if the connection pool is exhausted in the parent process
-   when the fork occurs, an empty pool will be copied into
-   the child process which will then hang because it has no connections.
-
 The above strategies will accommodate the case of an :class:`_engine.Engine`
-being shared among processes.  However, for the case of a transaction-active
-:class:`.Session` or :class:`_engine.Connection` being shared, there's no automatic
-fix for this; an application needs to ensure a new child process only
-initiate new :class:`_engine.Connection` objects and transactions, as well as ORM
-:class:`.Session` objects.  For a :class:`.Session` object, technically
-this is only needed if the session is currently transaction-bound, however
-the scope of a single :class:`.Session` is in any case intended to be
-kept within a single call stack in any case (e.g. not a global object, not
-shared between processes or threads).
-
+being shared among processes. The above steps alone are not sufficient for the
+case of sharing a specific :class:`_engine.Connection` over a process boundary;
+prefer to keep the scope of a particular :class:`_engine.Connection` local to a
+single process (and thread). It's additionally not supported to share any kind
+of ongoing transactional state directly across a process boundary, such as an
+ORM :class:`_orm.Session` object that's begun a transaction and references
+active :class:`_orm.Connection` instances; again prefer to create new
+:class:`_orm.Session` objects in new processes.
 
 
 API Documentation - Available Pool Implementations