Module pool (3.29.0)

Pools managing shared Session objects.

Specifies required API for concrete session pool implementations.

Concrete session pool implementation:

• "Pings" existing sessions via session.exists before returning them.

• Creates a new session, rather than blocking, when get is called on an empty pool.

• Discards the returned session, rather than blocking, when put is called on a full pool.

Concrete session pool implementation:

• Pre-allocates / creates a fixed number of sessions.

• "Pings" existing sessions via session.exists before returning them, and replaces expired sessions.

• Blocks, with a timeout, when get is called on an empty pool. Raises after timing out.

• Raises when put is called on a full pool. That error is never expected in normal practice, as users should be calling get followed by put whenever in need of a session.

Concrete session pool implementation:

• Pre-allocates / creates a fixed number of sessions.

• Sessions are used in "round-robin" order (LRU first).

• "Pings" existing sessions in the background after a specified interval via an API call (session.ping()).

• Blocks, with a timeout, when get is called on an empty pool. Raises after timing out.

• Raises when put is called on a full pool. That error is never expected in normal practice, as users should be calling get followed by put whenever in need of a session.

The application is responsible for calling ping at appropriate times, e.g. from a background thread.

Context manager: hold session checked out from a pool.

Concrete session pool implementation:

Deprecated: TransactionPingingPool no longer begins a transaction for each of its sessions at startup. Hence the TransactionPingingPool is same as PingingPool and maybe removed in the future.

In addition to the features of PingingPool, this class creates and begins a transaction for each of its sessions at startup.

When a session is returned to the pool, if its transaction has been committed or rolled back, the pool creates a new transaction for the session and pushes the transaction onto a separate queue of "transactions to begin." The application is responsible for flushing this queue as appropriate via the pool's begin_pending_transactions method.