Module resource_pool

Facade for resource pool.

Copyright © 2013 Alexei Krasnopolski

Version: 1.0.1

Introduced in: 2013-03-21

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

Description

Facade for resource pool.

Function Index

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

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.

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

borrow/1

borrow(Pool_name::atom() | pid()) -> Resource | {error, Reason}

Borrows resource from pool for client use.

return/2

return(Pool_name::atom(), Resource::term()) -> ok

Returns resource to pool after client does not need it more.

add/1

add(Pool_name::atom()) -> ok

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

invalidate/2

invalidate(Pool_name::atom(), Resource::term()) -> ok

Invalidates resource - makes it ready to dispose.

get_num_active/1

get_num_active(Pool_name::atom()) -> integer()

Returns number of active (busy) resource in pool.

get_num_idle/1

get_num_idle(Pool_name::atom()) -> integer()

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

get_number/1

get_number(Pool_name::atom()) -> integer()

Returns total number of resource in pool.

clear/1

clear(Pool_name::atom()) -> ok

Disposes all resources from the pool.

close/1

close(Pool_name::atom()) -> ok

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


Generated by EDoc, Apr 25 2013, 23:51:18.