/ 
Module-API-0.01
/ Module::API::Queue

NAME

Module::API::Queue - allow queueing of requests and non-blocking processing of them.

SYNOPSIS

use Module::API;
my $api = Module::API->new( server_url => 'http://api.example.com/api' );

$api->send_nb( 'request_name_1', \%data_1 );
$api->send_nb( 'request_name_2', \%data_2 );

while ( $api->queue->total_count ) {

    # check if a request has been completed
    if ( my $response = $api->queue->next_response ) {

        # deal with the response
        ...;
        next;
    }

    # do something whilst the requests are processed.
    ...;
}

DESCRIPTION

With API calls that go to a remote machine there is a time delay between sending the request and receiving the response. Module::API::Queue lets you do something during this delay.

All of the complexity of doing this is hidden from you. You need only send requests using $api->send_nb(...) and then check the queue from time to time to deal with the returned responses. In between checking the queue you are able to go off and do other things such as preparing more requests, updating a user interface or whatever.

HOW IT WORKS

Module::API::Queue maintains three internal lists:

to_send

The requests that have been added to the queue but have not been sent yet. The requests are sent one by one in the order in which they were added to the queue.

in_progress

The requests that have been sent but whose responses have not been fully received yet. There is no particular order. The number on this list is limited by slots.;

to_return

Requests that have been sent and their responses fully received. The are now ready for you to take back and deal with. They are in the order that they finished being received in - which may not be the order they were sent in.

Each time you call a method the internal lists are processed. This means that you should get back to the queue (or at least poke it) fairly often to ensure that it all works smoothly.

METHODS

new

my $api_queue = Module::API::Queue->new( api_class => 'Your::API::Class' );
my $api_queue = $api->queue;

Creates a new queue - but it is better to create an API object and access the queue through that. If the queue does not exist the API object will create it and configure it. The $api->queue is so preferred that it is used in all the examples other than this one.

slots

$slots = $api->queue->slots(123);    # Set slots to '123'
$slots = $api->queue->slots;         # Get the number of slots

Getter/setter for the number of slots - the maximum number of requests to have on in_progress at any one time. Defaults to 20. More requests can be added to the queue even when the limit is reached - but the requests will not be sent until there is a free slot. Returns the number set.

Changing the number of slots only affects adding requests to the in_progress list. Requests that are currently on the list are not affected. The queue can be paused by setting slots to zero.

add

$api->queue->add( $api_request, $api_request2, ... );

Add Module::API::Request objects to the queue. Always returns true.

*_count methods

my $number_to_send     = $api->queue->to_send_count;
my $number_in_progress = $api->queue->in_progress_count;
my $number_to_return   = $api->queue->to_return_count;

# Sum of all the above.
my $number_on_queue = $api->queue->total_count;

These return the number of requests in the various stages, or the total count. The queue is poked before the counts are made so that the values are up to date.

poke

$api->queue->poke;

Poke the queue. This means check the in_progress queue for requests that have finished and move them to the to_return queue. Then send any requests that are on the to_send.

This is done automatically by most of the other methods so you need not really ever do it. However it may prove useful to do this if you find yourself away from the queue for a long time so that the queue is kept current.

next_response

$api_response = $api->queue->next_response;

Get the next $api_response from the to_return list. The response is now removed from the list. If there are no more responses it returns undef.

DESTROY

The destroy method croaks if a queue is destroyed with items still on it.