view release on metacpan or  search on metacpan

lib/Class/TLB.pm  view on Meta::CPAN

The $tlb object will automatically balance the usage on the set of resources given and will avoid temporary resource failures:

    $tlb->oneFail() ; # This call is ok because only one resource will fail.

    $tlb->doFail()  ; # This call will confess an error because there is an 
                      # implementation error in the resource that makes it fail all the time.


=head2 Usage scenario:

You can use a Class::TLB wrapper to balance the usage of a set of similar distant resources.

In case the distant connection breaks in one of them, your client code will not suffer from it since
Class::TLB will avoid single resources failures.

For this to work, your resource must die or confess in case of disconnection.

In case there is a logical flaw in a resource method, Class::TLB will die with the error when you call it.

Because Class::TLB will attempt to use each resource instance and fail if all of them are failing.

=head1 BEST PRACTICES

=head2 Fail, but fail fast

If your resources represent a distant service accessed through the network, make sure that the connection failure dies quickly.

Long connection timeouts can cause waiting queries to accumulate in your application and can lead to an interruption of service, even if the other resources of the pool are perfectly healthy.

In particular, if your resources use cURL to connect to the distant service, make sure you set a short CURLOPT_CONNECTTIMEOUT (or CURLOPT_CONNECTTIMEOUT_MS) option.

=head1 CAVEATS

Your managed resources can not implement any of the methods implemented in Class::TLB.

All Class::TLB methods are prefixed with 'tlb_', making a collision very unlikely.

=head1 FUNCTIONS

=head2 new

=cut

sub new {
    my ( $class , $opts ) = @_ ;
    $opts ||= {} ;
    my $self = {
        '_tlb_queue' => List::PriorityQueue->new(), # The queue
        '_tlb_class' => undef , # The class of objects managed by this
        '_tlb_prototype' => undef , # The prototype of a resource. Typically the first instance given.
        '_tlb_usecount' => {} , # The usage count of each register object
        '_tlb_rcount' => 0 ,
        '_tlb_failpenalty' =>  $opts->{'failpenalty'} || 2 , # Delay a failed resource by 2 seconds
    } ;
    return bless $self , $class ;
}

=head2 isa

Overrides the UNIVERSAL::isa method to allow client code to transparently call isa method
on balanced resources.

Usage:
    if ( $this->isa('Class::TLB::Dummy')){
        ...
    }

=cut

sub isa{
    my $o  = shift;
    unless( ref $o ){
        return UNIVERSAL::isa($o , @_ );
    }
    if ( $o->tlb_prototype() ){
        return $o->tlb_prototype()->isa(@_);
    }
    return UNIVERSAL::isa($o , @_ );
}

=head2 can

Overrides the UNIVERSAL::can method to allow client code to transparently call can method
on balanced resources.

Usage:
    if ( $this->can('doSomething')){
        ...
    }

=cut

sub can{
    my $o  = shift;
    unless( ref $o ){
        return UNIVERSAL::can($o , @_ );
    }
    if ( $o->tlb_prototype() ){
        return $o->tlb_prototype()->can(@_);
    }
    return UNIVERSAL::can($o , @_ );
}




=head2 tlb_class

Returns the class of resources being load balanced.

usage:
    my $class = $tlb->tlb_class() ;

=cut

sub tlb_class{
    my ($self) =@_ ;
    return $self->{'_tlb_class'} ;
}

=head2 tlb_prototype

Returns an instance of resources being load balanced.

=cut

sub tlb_prototype{
    my ($self) = @_ ;
    return $self->{'_tlb_prototype'} ;
}

=head2 tlb_usecount

Returns the usage statistic hash of all sources.

usage:
    my $hcount = $tlb->tlb_usecount() ;

=cut

sub tlb_usecount{
    my ($self) = @_ ;
    return $self->{'_tlb_usecount'} ;