Ecto.Adapters.Pool behaviour
Behaviour for using a pool of connections.
Summary↑
| break(ref, timeout) | Break the active transaction or run |
| run(pool_mod, pool, timeout, fun) | Runs a fun using a connection from a pool |
| transaction(pool_mod, pool, timeout, fun) | Carry out a transaction using a connection from a pool |
Types ↑
Opaque connection reference.
Use inside run/4 and transaction/4 to retrieve the connection module and
pid or break the transaction.
t :: atom | pid
A pool process
depth :: non_neg_integer
The depth of nested transactions.
queue_time :: non_neg_integer
The time in microseconds spent waiting for a connection from the pool.
Functions
Specs:
- break(ref, timeout) :: :ok
Break the active transaction or run.
Calling connection/1 inside the same transaction or run (at any depth) will
return {:error, :noconnect}.
Examples
Pool.transaction(mod, pool, timout,
fn(ref, conn, 1, _queue_time) ->
{:ok, {_mod, ^conn}} = Pool.connection(ref)
:ok = Pool.break(ref, timeout)
{:error, :noconnect} = Pool.connection(ref)
end)
Pool.transaction(mod, pool, timeout,
fn(ref, _conn, 1, _queue_time) ->
:ok = Pool.break(ref, timeout)
{:error, :noconnect} =
Pool.transaction(mod, pool, timeout, fn(_, _, _, _) -> end)
end)Specs:
- run(module, t, timeout, (conn, queue_time | nil -> result)) :: {:ok, result} | {:error, :noproc | :noconnect} when conn: {module, pid}, result: var
Runs a fun using a connection from a pool.
The connection will be taken from the pool unless we are inside
a transaction/4 which, in this case, would already have a conn
attached to it.
Returns the value returned by the function wrapped in a tuple
as {:ok, value}.
Returns {:error, :noproc} if the pool is not alive or {:error, :noconnect}
if no connection is available.
Examples
Pool.run(mod, pool, timeout,
fn(_conn, queue_time) -> queue_time end)
Pool.transaction(mod, pool, timeout,
fn(_ref, _conn, 1, _queue_time) ->
{:ok, :nested} =
Pool.run(mod, pool, timeout, fn(_conn, nil) ->
:nested
end)
end)
Pool.run(mod, :pool1, timeout,
fn(_conn1, _queue_time1) ->
{:ok, :different_pool} =
Pool.run(mod, :pool2, timeout,
fn(_conn2, _queue_time2) -> :different_pool end)
end)Specs:
- transaction(module, t, timeout, (ref, conn, depth, queue_time | nil -> result)) :: {:ok, result} | {:error, :noproc | :noconnect | :notransaction} when conn: {module, pid}, result: var
Carry out a transaction using a connection from a pool.
Once a transaction is opened, all following calls to run/4 or
transaction/4 will use the same connection/worker. If break/2 is invoked,
all operations will return {:error, :noconnect} until the end of the
top level transaction.
A transaction returns the value returned by the function wrapped in a tuple
as {:ok, value}. Transactions can be nested and the depth shows the depth
of nested transaction for the module/pool combination.
Returns {:error, :noproc} if the pool is not alive, {:error, :noconnect}
if no connection is available or {:error, :notransaction} if called inside
a run/4 fun at depth 0.
Examples
Pool.transaction(mod, pool, timeout,
fn(_ref, _conn, 1, queue_time) -> queue_time end)
Pool.transaction(mod, pool, timeout,
fn(ref, _conn, 1, _queue_time) ->
{:ok, :nested} =
Pool.transaction(mod, pool, timeout, fn(_ref, _conn, 2, nil) ->
:nested
end)
end)
Pool.transaction(mod, :pool1, timeout,
fn(_ref1, _conn1, 1, _queue_time1) ->
{:ok, :different_pool} =
Pool.transaction(mod, :pool2, timeout,
fn(_ref2, _conn2, 1, _queue_time2) -> :different_pool end)
end)
Pool.run(mod, pool, timeout,
fn(_conn, _queue_time) ->
{:error, :notransaction} =
Pool.transaction(mod, pool, timeout, fn(_, _, _, _) -> end)
end)Callbacks
Specs:
- break(t, worker, timeout) :: :ok when worker: any
Break the current transaction or run.
Called when the function has failed and the connection should no longer be available to to the calling process.
Specs:
- checkin(t, worker, timeout) :: :ok when worker: any
Checkin a worker/connection to the pool.
Called when the top level run/4 finishes, if break/2 was not called
inside the fun.
Specs:
- checkout(t, timeout) :: {:ok, worker, conn, queue_time} | {:error, :noproc | :noconnect} when worker: any, conn: {module, pid}
Checkout a worker/connection from the pool.
The connection should not be closed if the calling process exits without returning the connection.
Returns {:ok, worker, conn, queue_time} on success, where worker is the
worker term and conn is a 2-tuple contain the connection’s module and
pid. The conn tuple can be retrieved inside a transaction/4 with
connection/1.
Returns {:error, :noproc} if the pool is not alive and
{:error, :noconnect} if a connection is not available.
Specs:
- close_transaction(t, worker, timeout) :: :ok when worker: any
Close the transaction and signal to the worker the work with the connection is complete.
Called once the transaction at depth 1 is finished, if the transaction
is not broken with break/2.
Specs:
- open_transaction(t, timeout) :: {:ok, worker, conn, queue_time} | {:error, :noproc | :noconnect} when worker: any, conn: {module, pid}
Open a transaction with a connection from the pool.
The connection should be closed if the calling process exits without returning the connection.
Returns {:ok, worker, conn, queue_time} on success, where worker is the
worker term and conn is a 2-tuple contain the connection’s module and
pid. The conn tuple can be retrieved inside a transaction/4 with
connection/2.
Returns {:error, :noproc} if the pool is not alive and
{:error, :noconnect} if a connection is not available.
Specs:
- start_link(module, opts) :: {:ok, pid} | {:error, any} when opts: Keyword.t
Start a pool of connections.
module is the connection module, which should define the
Ecto.Adapters.Connection callbacks, and opts are its (and the pool’s)
options.
A pool should support the following options:
:name- The name of the pool:size- The number of connections to keep in the pool
Returns {:ok, pid} on starting the pool.
Returns {:error, reason} if the pool could not be started. If the reason
is {:already_started, pid}}` a pool with the same name has already been
started.
Specs:
- stop(t) :: :ok
Stop a pool.