Module resource_pool

Description
Function Index
Function Details

Facade for resource pool.

Version: 1.0.3

Introduced in: 2013-03-21

Authors: Alexei Krasnopolski (krasnop@bellsouth.net) [web site: http://krasnopolski.org/].

Function Index

add/1	Adds one more resource to pool (as an idle resource).
borrow/1	Borrows resource from pool for client use.
clear/1	Disposes all resources from the pool.
close/1	Disposes all resources from the pool and close the pool (shut down generic server).
get_num_active/1	Returns number of active (busy) resource in pool.
get_num_idle/1	Returns number of idle (ready to use) resource in pool.
get_number/1	Returns total number of resource in pool.
invalidate/2	Invalidates resource - makes it ready to dispose.
new/3	Creates and runs new generic server for resource_pool with registered name `Pool_name`.
new/4	Creates and runs new generic server for resource_pool with registered name `Pool_name`.
return/2	Returns resource to pool after client does not need it more.

Function Details

new/3

new(Pool_name::atom(), Factory_module::atom(), Resource_metadata::term()) -> {ok, Resource} | ignore | {error, Error}

Creates and runs new generic server for resource_pool 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.

new/4

new(Pool_name::atom(), Factory_module::atom(), Resource_metadata::term(), Options::[{Key, Value}]) -> {ok, Resource} | ignore | {error, Error}

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.