NAME

ResourcePool::LoadBalancer - A LoadBalancer across ResourcePools.

SYNOPSIS

use ResourcePool::LoadBalancer;

my $loadbalancer = ResourcePool::LoadBalancer->new($key, @options);


$loadbalancer->add_pool($some_ResourcePool);
$loadbalancer->add_pool($some_other_ResourcePool);
$loadbalancer->add_pool($third_ResourcePool);


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

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

DESCRIPTION

The LoadBalancer is a generic way to spread requests to different ResourcePools to increase performance and/or availibility.

Besides the construction the interface of a LoadBalancer is the same as the interface of a ResourcePool. This makes it very simple to replace a existing ResourcePool with a LoadBalancer.

The methods of the LoadBalancer follow now in order of usage, please have a look at the EXAMPLE below if you have still questions.

LoadBalancer->new()

Creates a new LoadBalancer. This method takes one key to identify the LoadBalancer (used by ResourcePool::Singelton). It is recommended to use some meaningful string as key, since this is used when errors are reported. This key is internally used to distingush between different pool types, e.g. if you have to LoadBalancer one for DBI connections to different servers and use parallel another LoadBalancer for Net::LDAP connections.

Options

Policy

With this option you can specify which ResourcePool is used if you ask the LoadBalancer for a Resource. LeastUsage takes always the ResourcePool with the least used Resources. This is usually a vital inidcator for the machine with the least load. RoundRobin iterates over all available ResourcePools regardless of the usage of the ResourcePools. FallBack uses always the first ResourcePool if it works, only if there is a problem it takes the second and so on.

In every case the LoadBalancer tries to find a valid Resource for you.

Default: LeastUsage

MaxTry

The MaxTry option specifies how many ResourcePools the LoadBalancer queries before it gives up and return a null on the get() call. This option is identical to the same named option from the ResourcePool.

Default: 2

$loadbalancer->add_pool($resourcepool, @options)

Adds a ResourcePool object to the LoadBalancer. You must call this method multiple to add more Pools.

There are two options which affect the way the LoadBalancer selects the ResourcePools. Weight may make one ResourcePool more relevant then others. A ResourcePool with a high Weight is more expancive then a ResourcePool with a low Weight and will be used less frequent by the LoadBalancer. SuspendTimeout specifies the timeout in seconds, see below.

Defaults: Weight = 100, SuspendTimout = 5

$loadbalancer->get()

Returns a resource. This resource has to be given back via the free() or fail() method. The get() method calls the get() method of the ResourcePool and might therfore return undef if no valid resource could be found in the ResourcePool. In that case the LoadBalancer tries up to MaxTry times to get a valid resource out of the ResourcePools. If the LoadBalancer finds a invalid ResourcePool (a ResourcePool which returns a undef) it suspends this ResourcePool and re-applies the Policy to get a valid resource. The SuspendTimeout is configureable on a per-ResourcePool basis.

$loadbalancer->free($resource)

Returns a resource to the ResourcePool it comes from. Basically the same as the free() method of the ResourcePool.

$loadbalancer->fail($resource)

Maks the resource as bad. Basically the same as the fail() method of the ResourcePool.

EXAMPLE

use ResourcePool;
use ResourcePool::Factory::Net::LDAP;
use ResourcePool::LoadBalancer;

# create a pool to a ldap server
my $factory1 = ResourcePool::Factory::Net::LDAP->new("ldap.domain.com");
my $pool1    = ResourcePool->new($factory1);

# create a pool to another ldap server
my $factory2 = ResourcePool::Factory::Net::LDAP->new("backupldap.domain.com");
my $pool2    = ResourcePool->new($factory1);

# create a empty loadbalancer with a FallBack policy
my $loadbalancer = ResourcePool::LoadBalancer->new("LDAP", "FallBack");

# add the first pool to the LoadBalancer
# since this pool was configured to use the FallBack policy, this is
# the primary used pool
$loadbalancer->add_pool($pool1);

# add the second pool to the LoadBalancer.
# This pool is only used when first pool failes
$loadbalancer->add_pool($pool2);


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

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

SEEL ALSO

ResourcePool(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.