Module pool (3.8.0)

Pools managing shared Session objects.

Classes

AbstractSessionPool

AbstractSessionPool(labels=None)

Specifies required API for concrete session pool implementations.

Parameter
Name	Description
`labels`	`dict (str -> str) or None` (Optional) user-assigned labels for sessions created by the pool.

BurstyPool

BurstyPool(target_size=10, labels=None)

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.

Parameters
Name	Description
`target_size`	`int` max pool size
`labels`	`dict (str -> str) or None` (Optional) user-assigned labels for sessions created by the pool.

FixedSizePool

FixedSizePool(size=10, default_timeout=10, labels=None)

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.

Parameters
Name	Description
`size`	`int` fixed pool size
`default_timeout`	`int` default timeout, in seconds, to wait for a returned session.
`labels`	`dict (str -> str) or None` (Optional) user-assigned labels for sessions created by the pool.

PingingPool

PingingPool(size=10, default_timeout=10, ping_interval=3000, labels=None)

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.

Parameters
Name	Description
`size`	`int` fixed pool size
`default_timeout`	`int` default timeout, in seconds, to wait for a returned session.
`ping_interval`	`int` interval at which to ping sessions.
`labels`	`dict (str -> str) or None` (Optional) user-assigned labels for sessions created by the pool.

SessionCheckout

SessionCheckout(pool, **kwargs)

Context manager: hold session checked out from a pool.

Parameter
Name	Description
`pool`	`concrete subclass of AbstractSessionPool` Pool from which to check out a session.

TransactionPingingPool

TransactionPingingPool(
    size=10, default_timeout=10, ping_interval=3000, labels=None
)

Concrete session pool implementation:

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.

Parameters
Name	Description
`size`	`int` fixed pool size
`default_timeout`	`int` default timeout, in seconds, to wait for a returned session.
`ping_interval`	`int` interval at which to ping sessions.
`labels`	`dict (str -> str) or None` (Optional) user-assigned labels for sessions created by the pool.