View Source DBConnection.Ownership (db_connection v2.5.0)
A DBConnection pool that requires explicit checkout and checkin as a mechanism to coordinate between processes.
options
Options
:ownership_mode- When mode is:manual, all connections must be explicitly checked out before by usingownership_checkout/2. Otherwise, mode is:autoand connections are checked out implicitly.{:shared, owner}mode is also supported so processes are allowed on demand. On all cases, checkins are explicit viaownership_checkin/2. Defaults to:auto.:ownership_timeout- The maximum time that a process is allowed to own a connection, default120_000. This timeout exists mostly for sanity checking purposes and can be increased at will, since DBConnection automatically checks in connections whenever there is a mode change.:ownership_log- TheLogger.levelto log ownership changes, ornilnot to log, defaultnil.
There are also two experimental options, :post_checkout and :pre_checkin
which allows a developer to configure what happens when a connection is
checked out and checked in. Those options are meant to be used during tests,
and have the following behaviour:
:post_checkout- it must be an anonymous function that receives the connection module, the connection state and it must return either{:ok, connection_module, connection_state}or{:disconnect, err, connection_module, connection_state}. This allows the developer to change the connection module on post checkout. However, in case of disconnects, the returnconnection_modulemust be the same as theconnection_modulegiven. Defaults to simply returning the given connection module and state.:pre_checkin- it must be an anonymous function that receives the checkin reason (:checkin,{:disconnect, err}or{:stop, err}), the connection module and the connection state returned bypost_checkout. It must return either{:ok, connection_module, connection_state}or{:disconnect, err, connection_module, connection_state}where the connection module is the module given to:post_checkoutDefaults to simply returning the given connection module and state.
callers-lookup
Callers lookup
When checking out, the ownership pool first looks if there is a connection
assigned to the current process and then checks if there is a connection
assigned to any of the processes listed under the $callers process
dictionary entry. The $callers entry is set by default for tasks from
Elixir v1.8.
You can also pass the :caller option on checkout with a pid and that
pid will be looked up first, instead of self(), and then we fall back
to $callers.
Link to this section Summary
Functions
Allows the process given by allow to use the connection checked out
by owner_or_allowed.
Checks a connection back in.
Explicitly checks a connection out from the ownership manager.
Changes the ownership mode.
Link to this section Functions
@spec ownership_allow( GenServer.server(), owner_or_allowed :: pid(), allow :: pid(), Keyword.t() ) :: :ok | {:already, :owner | :allowed} | :not_found
Allows the process given by allow to use the connection checked out
by owner_or_allowed.
It may return :ok if the connection is checked out.
{:already, :owner | :allowed} if the allow process already
has a connection. owner_or_allowed may either be the owner or any
other allowed process. Returns :not_found if the given process
does not have any connection checked out.
@spec ownership_checkin(GenServer.server(), Keyword.t()) :: :ok | :not_owner | :not_found
Checks a connection back in.
A connection can only be checked back in by its owner.
@spec ownership_checkout(GenServer.server(), Keyword.t()) :: :ok | {:already, :owner | :allowed}
Explicitly checks a connection out from the ownership manager.
It may return :ok if the connection is checked out.
{:already, :owner | :allowed} if the caller process already
has a connection, :error if it could be not checked out or
raise if there was an error.
@spec ownership_mode( GenServer.server(), :auto | :manual | {:shared, pid()}, Keyword.t() ) :: :ok | :already_shared | :not_owner | :not_found
Changes the ownership mode.
mode may be :auto, :manual or {:shared, owner}.
The operation will always succeed when setting the mode to
:auto or :manual. It may fail with reason :not_owner
or :not_found when setting {:shared, pid} and the
given pid does not own any connection. May return
:already_shared if another process set the ownership
mode to {:shared, _} and is still alive.