db_connection v0.2.5 DBConnection.Ownership

A DBConnection.Pool that requires explicit checkout and checking 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.

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).

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 ownwership mode

Functions

ownership_allow(manager, owner, allow, opts)

Specs

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.

ownership_checkin(manager, opts)

Specs

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.

ownership_checkout(manager, opts)

Specs

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.

ownership_mode(manager, mode, opts)

Specs

ownership_mode(GenServer.server, :auto | :manual | {:shared, pid}, Keyword.t) ::
  :ok |
  :already_shared |
  :not_owner |
  :not_found

Changes the ownwership 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.