The ResourcePool package consists of three major parts:
- Command framework
The ResourcePool is used to manage a pool of persistent connections (or more generally "resources"). Every resource in a pool is exactly equivalent to the others since all of them are created through the same factory.
If you want to make a pool of different resources (e.g. connections to different databases) you have to use the ResourcePool::LoadBalancer.
The ResourcePool uses two other classes to operate:
used to create resources
used as wrapper to implement a unique interface to all resources
To create a ResourcePool you need a ResourcePool::Factory which is able to create the ResourcePool::Resource's you want to use. The ResourcePool will then use this factory to create ResourcePool::Resource objects as required.
The ResourcePool::Resource itself creates the finally interesting objects like DBI or Net::LDAP and provides a standard way to perform the common operations required by ResourcePool to work with this resource.
The ResourcePool::Factory and ResourcePool::Resource classes are base classes to inherit the specialized classes for your resource from. The classes to handle DBI and Net::LDAP resources are available as separate distributions on CPAN.
After creating a ResourcePool you can use the get() method to obtain a resource. The get() method will return the DBI or Net::LDAP object which can be used as usually. Afterwards you have to hand the resource back into the pool by calling the free() method.
Please have a look to the ResourcePool documentation for further details.
To construct a ResourcePool::LoadBalancer you need one or more ResourcePools. After construction a ResourcePool::LoadBalancer behaves like a ResourcePool, so you can call the get() method to obtain a resource and can use the Command strategy.
The ResourcePool::LoadBalancer can be configured to use a different ResourcePool every time you call the get() method. The ResourcePool::LoadBalancer can also detect a problem with a ResourcePool (e.g. because the related server is down) and will hide such problems from you.
There are currently three "Policies" which change the way the ResourcePool::LoadBalancer uses the configured resources:
The ResourcePool package includes a framework which can be used to execute commands like described in the GOF book "Design Patterns". You can use this pattern to avoid manual use of the get(), free() and fail() methods. The common code used to work with ResourcePool or ResourcePool::LoadBalancer (get resource, use it, return it to the pool) has been encapsulated into the execute() method.
The Command framework will it make easier to handle errors, and is capable of re-trying the complete work if an error occured. Using this pattern can help you to forget (nearly) about error handling since everything is handled in ResourcePool and ResourcePool::LoadBalancer. More details how to use this pattern can be found in the ResourcePool::Command::Execute documentation.
This pattern does also allow to use ResourcePool and ResourcePool::LoadBalancer for a complete new type of resources like SOAP::Lite. In that case you can use ResourcePool::LoadBalancer to spread load and handle failover for SOAP RPC calls. Have a look at ResourcePool::Command::SOAP::Lite::Call for details about this approach.
You should have the big picture of ResourcePool and ResourcePool::LoadBalancer now, time to go into the details at the ResourcePool and ResourcePool::LoadBalancer documentation. If you loose track of all these modules consult the ResourcePool::UML diagram.
The best entry point for the Command pattern is the ResourcePool::Command::Execute documentation. Have a look at the ResourcePool::Command::DBI::Execute documentation for a database related example or ResourcePool::Command::SOAP::Lite::Call documentation for a SOAP RPC example.
To learn more about how to implement your own resource extensions have a look to the ResourcePool::ExtensionGuide.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.