Resource pool v1.0.3 ResourcePool View Source

Facade for resource pool.

Link to this section Summary

Functions

Adds one more resource to pool (as an idle resource).

Borrows resource from pool. Returns resource pid for client use.

Disposes all resources from the pool.

Disposes all resources from the pool and close the pool (shut down generic server).

Returns number of active (busy) resources in pool.

Returns number of idle (ready to use) resources in pool.

Returns total number of resources in pool as a tuple {active, idle}.

Invalidates resource - makes it ready to dispose.

Creates and runs new generic server for ResourcePool with registered name pool_name. The new resource pool will use factory_module as a resource factory and resource_metadata as a metadata to create a new resource.

Creates and runs new generic server for ResourcePool with registered name pool_name. The new resource pool will use factory_module as a resource factory and resource_metadata as a metadata to create a new resource. options defines behaviour of the pool. The available options are

The function sends resource to the pool's idle container after client does not need it any more.

Link to this section Functions

Specs

add(atom() | pid()) :: :ok

Adds one more resource to pool (as an idle resource).

Specs

borrow(atom() | pid()) :: pid() | {:error, any()}

Borrows resource from pool. Returns resource pid for client use.

Specs

clear(atom() | pid()) :: :ok

Disposes all resources from the pool.

Specs

close(atom() | pid()) :: :ok

Disposes all resources from the pool and close the pool (shut down generic server).

Link to this function

get_num_active(pool_name)

View Source

Specs

get_num_active(atom() | pid()) :: integer()

Returns number of active (busy) resources in pool.

Specs

get_num_idle(atom() | pid()) :: integer()

Returns number of idle (ready to use) resources in pool.

Specs

get_number(atom() | pid()) :: {integer(), integer()}

Returns total number of resources in pool as a tuple {active, idle}.

Link to this function

invalidate(pool_name, resource)

View Source

Specs

invalidate(atom() | pid(), pid()) :: :ok

Invalidates resource - makes it ready to dispose.

Link to this function

new(pool_name, factory_module, resource_metadata)

View Source

Specs

new(atom() | pid(), module(), list()) ::
  :ignore | {:error, any()} | {:ok, pid()}

Creates and runs new generic server for ResourcePool with registered name pool_name. The new resource pool will use factory_module as a resource factory and resource_metadata as a metadata to create a new resource.

Link to this function

new(pool_name, factory_module, resource_metadata, options)

View Source

Specs

new(atom() | pid(), module(), list(), list()) ::
  :ignore | {:error, any()} | {:ok, pid()}

Creates and runs new generic server for ResourcePool with registered name pool_name. The new resource pool will use factory_module as a resource factory and resource_metadata as a metadata to create a new resource. options defines behaviour of the pool. The available options are:

  • max_active: integer() - defines the maximum number of resource instances that can be allocated by the pool at a given time. If non-positive, there is no limit to the number of instances that can be managed by the pool at one time. When max_active is reached, the pool is said to be exhausted. The default setting for this parameter is 8.

  • max_idle: integer() defines the maximum number of objects that can sit idle in the pool at any time. If negative, there is no limit to the number of objects that may be idle at one time. The default setting for this parameter equals max_active.

  • min_idle: integer() defines the minimum number of "sleeping" instances in the pool. Default value is 0.

  • test_on_borrow: boolean() If true the pool will attempt to validate each resource before it is returned from the borrow function (Using the provided resource factory's validate function). Instances that fail to validate will be dropped from the pool, and a different object will be borrowed. The default setting for this parameter is false.

  • test_on_return: boolean() If true the pool will attempt to validate each resource instance before it is returned to the pool in the return function (Using the provided resource factory's validate function). Objects that fail to validate will be dropped from the pool. The default setting for this option is false.

  • fifo: boolean() The pool can act as a LIFO queue with respect to idle resource instances always returning the most recently used resource from the pool, or as a FIFO queue, where borrow always returns the oldest instance from the idle resource list. fifo determines whether or not the pool returns idle objects in first-in-first-out order. The default setting for this parameter is false.

  • when_exhausted_action: (:fail | :block | :grow) specifies the behaviour of the borrow function when the pool is exhausted:

    • :fail will return an error.
    • :block will block until a new or idle object is available. If a positive max_wait value is supplied, then borrow will block for at most that many milliseconds, after which an error will be returned. If max_wait is non-positive, the borrow function will block infinitely.
    • :grow will create a new object and return it (essentially making max_active meaningless.) The default when_exhausted_action: setting is :block and the default max_wait: setting is :infinity. By default, therefore, borrow will block infinitely until an idle instance becomes available.
  • max_wait: (integer() | infinity) The maximum amount of time to wait when the borrow function is invoked, the pool is exhausted (the maximum number of "active" resource instances has been reached) and when_exhausted_action: equals :block.

  • max_idle_time: (integer() | infinity) The maximum amount of time an resource instance may sit idle in the pool, with the extra condition that at least min_idle amount of object remain in the pool. When infinity, no instances will be evicted from the pool due to maximum idle time limit.

Link to this function

return(pool_name, resource)

View Source

Specs

return(atom() | pid(), pid()) :: :ok

The function sends resource to the pool's idle container after client does not need it any more.