NAME

ResourcePool - A connection cacheing and pooling class.

SYNOPSIS

use ResourcePool;
use ResourcePool::Factory;

my $factory = ResourcePool::Factory->new();
my $pool = ResourcePool->new($factory, @Options);

my $resource = $pool->get();  # get a resource out of the pool
[...]                         # do something with $resource
$pool->free($resource);       # give it back to the pool

$pool->fail($resource);       # give back a failed resource

DESCRIPTION

The ResourcePool is a generic connection cacheing and pooling management facility. It might be used in an Apache/mod_perl environment to support connection caching like Apache::DBI for non-DBI resources (e.g. Net::LDAP). Its also usefull in a stand alone perl application to handle connection pools.

The key benefit of ResourcePool is the generic design which makes it easily extendable to new resource types.

The ResourcePool has a simple check mechanism to dedect and close broken connections (e.g. if the database server was restarted) and opens new connections if possible.

The ResourcePool itself handles always exactly equivalent connections (e.g. connections to the same server whith the same username and password) and is therefore not able to do a loadbalancing. The ResourcePool::LoadBalancer class is able to do a simple load balancing across different servers and increases the overall availibility by dedecting dead servers.

ResourcePool->new()

Creates a new ResourcePool. It uses a previous created ResourcePool if possible. So if you call the new method with the same arguments twice, the second call returns the ResourcePool created with the first call. This is even true if you call the new method while handling different Apache mod_perl requests. (This is implemented using the Singelton class included in this distribution)

$factory

Specifies the Factory to create new resources. (see ResourcePool::Factory)

OPTIONS

Max

Specifies the maximum concurrent resources managed by this Pool. If the limit is reached the get() method may return undef.

Default: 5

MaxTry

Specifies how many dead Resources the get() method checks before it returns undef. Normally the get() method doesn't return dead resources (e.g. broken connections). In the case there is a broken connection in the Pool, the get() method throws it away and takes the next resource out of the pool. The get() method tries not more then MaxTry resources before it returns undef.

Default: 2

PreCreate

Specifies how many Resources the Pool creates in advance.

Default: 0

$pool->get()

Returns a resource. This resource has to be given back via the free() or fail() method. The get() method calls the precheck() method of the according Resource (see ResourcePool::Resource) to determine if a resource is valid. The get() method may return undef if there is no valid resource available. (e.g. because the Max or the MaxTry options are reached)

$pool->free($resource)

Returns a resource to the pool. This resource will be re-used by get() calls. The free() method calls the postcheck() method of the Resource to dertermine if the resource is valid.

$pool->fail($resource)

Marks a resource as bad. The ResourcePool will throw this resource away and NOT return it to the pool of available connections.

SEE ALSO

ResourcePool::Resource(3pm), ResourcePool::Factory(3pm), ResourcePool::Factory::DBI(3pm), ResourcePool::Factory::Net::LDAP(3pm)

AUTHOR

Copyright (C) 2001 by Markus Winand <mws@fatalmind.com>

This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.