NAME

POE::Component::ResourcePool::Resource::Semaphore - numerical semaphore resource.

SYNOPSIS

        # this example will allow up to 10 concurrent URL fetches by blocking
        # sessions until they get their resources allocated.

        # the control could be inverted such that the main loop queues up many
        # requests, each of which creates a fetcher session.

        # the actual URL fetching code has been omitted for brevity.


        # first create the semaphore:
        my $sem = POE::Component::ResourcePool::Resource::Semaphore->new( initial_value => 10 );


        # then add it to a pool:
        my $pool = POE::Component::ResourcePool->new(
                resources => { connections => $sem },
        )


        # finally queue requests that will trigger the callback when they are
        # fulfilled.

        foreach my $url ( @urls ) {
                POE::Session->create(
                        inline_states => {
                                _start => sub {
                                        my ( $kernel, $heap ) = @_[KERNEL, HEAP];

                                        $pool->request(
                                                params => { connections => 1 },
                                                event  => "fetch",
                                        );
                                },
                                fetch => sub {
                                        my ( $kernel, $heap ) = @_[KERNEL, HEAP];

                                        ... fetch ...

                                        $heap->{request}->dismiss;
                                },
                        },
                );
        }

DESCRIPTION

This class provides a numerical semaphore based resource for POE::Component::ResourcePool.

This is useful for throttling resources, for example the number of concurrent jobs or a symbolic value for memory units.

The semaphore will fulfill requests for numerical values (the default value is 1) as long as it's counter remains above zero.

Requests asking for more than the initial value will fail immediately.

METHODS

could_allocate

Returns true if the value is numerically less than or equal to the semaphore's initial value.

try_allocating

Successfully allocates if the value is numerically less than or equal to the semaphore's current value.

finalize_allocation

Finalizes an allocation by deducting the requested value from the semaphore's current value, and returns the request value as the parameter for the resource.

free_allocation

Adds the freed value to the semaphore's current value, and notifies all pools.

Since allocation attempts are a simple procedure no attempt at request tracking is made, and all pools will be notified unconditionally.

ATTRIBUTES

initial_value

The initial value of the semaphore.

Required.

value

The current value of the semaphore.

Read only.