NAME

SYNOPSIS

 use ResourcePool::LoadBalancer;
 
 my $loadbalancer = ResourcePool::LoadBalancer->new("key", MaxTry => 10);
 
 $loadbalancer->add_pool($some_ResourcePool);
 $loadbalancer->add_pool($some_other_ResourcePool);
 $loadbalancer->add_pool($third_ResourcePool);
 
 my $resource = $loadbalancer->get();  # get a resource from one pool
                                       # 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

Besides the construction the interface of ResourcePool::LoadBalancer is the same as the interface of ResourcePool. This makes it very simple to change a program which uses ResourcePool to use the ResourcePool::LoadBalancer by just changing the construction (which is hopefully kept at a central point in your program).

EXAMPLES

 use ResourcePool;
 use ResourcePool::Factory::Net::LDAP;
 use ResourcePool::LoadBalancer;
 
 ### LoadBalancer setup 
 
 # create a pool to a ldap server
 my $factory1 = ResourcePool::Factory::Net::LDAP->new("ldap.you.com");
 my $pool1    = ResourcePool->new($factory1);
 
 # create a pool to another ldap server
 my $factory2 = ResourcePool::Factory::Net::LDAP->new("ldap2.you.com");
 my $pool2    = ResourcePool->new($factory2);
 
 # create a empty loadbalancer with a FailBack policy
 my $loadbalancer = ResourcePool::LoadBalancer->new("LDAP", 
                        Policy => "FailBack");
 
 # add the first pool to the LoadBalancer
 # since this LoadBalancer was configured to use the FailBack
 # 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 fails
 $loadbalancer->add_pool($pool2);
 
 ### LoadBalancer usage (no difference to ResourcePool)
 for (my $i = 0; $i < 1000000 ; $i++) {
    my $resource = $loadbalancer->get();  # get a resource from one pool
                                          # according to the policy
    if (defined $resource) {
       eval {
          #[...]                          # do something with $resource
          $loadbalancer->free($resource); # give it back to the pool
       }; 
       if ($@) { # an exception happened
          $loadbalancer->fail($resource); # give back a failed resource
       }
    } else {
       die "The LoadBalancer was not able to obtain a valid resource\n";
    }
 }

Please notice that the get()/ free() stuff in this example in INSIDE the loop. This is very important to make sure the load balancing and fail over works. As for the ResourcePool the smartness of the load balancer lies in the get() method, so if you do not call the get() method regular you can not expect the load balancer to handle load balancing or fail over.

The example above does not do any load balancing since the policy was set to FailBack. If you would change this to RoundRobin or LeastUsage you would spread the load across both servers.

You can directly copy and past the example above and try to run it. If you do not change the hostnames you will just see how it fails, but even this will tell you a lot about how it works. Give it a try.

Now lets make a slightly more complex configuration. Imagine you have three ldap servers: one master where you do your write access, two replicas where you do the read access. Now we want ResourcePool::LoadBalancer to implement a load balancing across the two replicas but we want it to use the master also for read access if both replicas are not available.

This setup is simple if you keep in mind what I have said about the ResourcePool::LoadBalancer interface: "Beside the construction the interface of ResourcePool::LoadBalancer is the same as the interface of ResourcePool. This means that it is possible to make a nested load balancer chain.

 use ResourcePool;
 use ResourcePool::Factory::Net::LDAP;
 use ResourcePool::LoadBalancer;
 
 ### LoadBalancer setup 
 
 # create a pool to the master
 my $masterfactory   = ResourcePool::Factory::Net::LDAP->new("master");
 my $master          = ResourcePool->new($masterfactory);
 
 # create pools to the replicas
 my $replica1factory = ResourcePool::Factory::Net::LDAP->new("replica1");
 my $replica1        = ResourcePool->new($replica1factory);
 
 my $replica2factory = ResourcePool::Factory::Net::LDAP->new("replica2");
 my $replica2        = ResourcePool->new($replica2factory);
 
 # create the loadbalancer to spread load across the two replicas
 # using the default Policy LeastUsage
 my $replicaLB       = ResourcePool::LoadBalancer->new("LDAP-Replica");
 $replicaLB->add_pool($replica1);
 $replicaLB->add_pool($replica2);
 
 # create a superior loadbalancer which handles the FailBack to the
 # master if both replicas fail.
 my $loadbalancer = ResourcePool::LoadBalancer->new("LDAP", 
                        Policy => "FailBack");
 $loadbalancer->add_pool($replicaLB);   # HERE IS THE MAGIC
 $loadbalancer->add_pool($master);
 
 ### LoadBalancer usage is the same as above, therefore skipped here

You should keep in mind that this configuration causes a multiplication of the timeout's which are done because of the > settings. In the example above the sleeps sum up to 60 seconds.

SEE ALSO

AUTHOR

    Copyright (C) 2001-2009 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.