db_connection

v1.1.3

db_connection v1.1.3 DBConnection.Ownership View Source

A DBConnection.Pool that requires explicit checkout and checkin as a mechanism to coordinate between processes.

Options

  • :ownership_pool - The actual pool to use to power the ownership mechanism. The pool is started when the ownership pool is started, although this option may also be given on ownership_checkout/2 allowing developers to customize the pool checkout/checkin
  • :ownership_mode - When mode is :manual, all connections must be explicitly checked out before by using ownership_checkout/2. Otherwise, mode is :auto and connections are checked out implicitly. {:shared, owner} mode is also supported so processes are allowed on demand. On all cases, checkins are explicit via ownership_checkin/2. Defaults to :auto.
  • :ownership_timeout - The maximum time that a process is allowed to own a connection, default 15_000.
  • :ownership_log - The Logger.level to log ownership changes, or nil not to log, default nil.

If the :ownership_pool has an atom name given in the :name option, an ETS table will be created and automatically used for lookups whenever the name is used on checkout.

Finally, if the :caller option is given on checkout with a pid and no pool is assigned to the current process, a connection will be allowed from the given pid and used on checkout with :pool_timeout of :infinity. This is useful when multiple tasks need to collaborate on the same connection (hence the :infinity timeout).

Link to this section Summary

Functions

ownership_allow(manager, owner, allow, opts)

Allows the process given by allow to use the connection checked out by owner_or_allowed

ownership_checkin(manager, opts)

Checks a connection back in

ownership_checkout(manager, opts)

Explicitly checks a connection out from the ownership manager

ownership_mode(manager, mode, opts)

Changes the ownership mode

Link to this section Functions

Link to this function ownership_allow(manager, owner, allow, opts) View Source 
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.

Link to this function ownership_checkin(manager, opts) View Source 
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.

Link to this function ownership_checkout(manager, opts) View Source 
ownership_checkout(GenServer.server(), Keyword.t()) ::
  :ok |
  {:already, :owner | :allowed} |
  :error |
  no_return()

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.

Link to this function ownership_mode(manager, mode, opts) View Source 
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.