/ 
Cache-Memcached-Queue-0.0.6
River stage zero No dependents
/ Cache::Memcached::Queue

NAME

Cache::Memcached::Queue - Very simple way to create multiple queues and save them on Memcached

VERSION

Version 0.0.6

alpha version

DESCRIPTION

This works by taking advantage of Memcached infrastructure. In other words, the 'keys' will be strings that are names of indexes for some basic values that are sufficient to represent a queue structure. This basic values are: first, last, size and max_enq.

In order to have multiple queues in the same Memcached server, a prefix are added to every index on keys of Memcached. So, every key in memcached have the following struct on his name: <PREFIX>_<ID>_<INDEX_NUMBER OR NAME>

PREFIX - This is defined by the 'id_prefix' attribute. The default value is 'CMQID_'
ID - This is defined by the 'id' attribute. If the 'id' attribute was not defined, a UUID will be defined for it automatically.
INDEX_NUMBER OR NAME - If some data is a item in the queue, so this must be a sequential number, for example: 'CMQID_1_1' This can be the first element from queue with id 1. If some data in the queue is a pointer, this pointer must be named, for example: 'CMQID_1_first' This is the pointer to the first element in queue.

SYNOPSIS

This module implements a simple scheme of a Queue.

    use Cache::Memcached::Queue;

    my $q = Cache::Memcached::Queue->new( name => 'foo', 
						max_enq => 10, 
						servers => [{address => '127.0.0.1:11211'}, #other Cache::Memcached::Fast options here... ], 
					  	id => 1,
                        id_prefix => 'MYQUEUE',
					)->init;

    			
    #ENQUEUE
    #do this
    $q->enq({value => $somevalue});

    #DEQUEUE
    my $queue_first_value = $q->deq();

    #WHAT'S THE SIZE OF MY QUEUE ?
    my $size = $q->size();

    #CLEANUP
    $q->cleanup(); #removes everything from object and from Memcached

init()

Initialize object attributes and check attributes problems. If all is ok, returns the reference to object. Otherwise returns undef and trows an exception

load()

Try to load the queue pointers from Memcached. If works, will return true. Otherwise will return false.

enq($parameters)

Try to make a 'enqueue' operation. That means tha 'last' index pointer will be readjusted to the next index. So the value can be recorded on Memcached.

The parameters are validated, and the valid parameters are:

value - A value that presupposes that you want to save
serialize - If you need the value to be serialized, you must set serialized to true(1). NOT IMPLEMENTED YET.

Example: $enq({value => 'some_value'});

Example2: $enq({value => $some_object_or_structure, serialize => 1, });

If this work, the method will return true. Otherwise, will return false.

deq()

Try to make a 'dequeue' operation on Queue. That means the first value of queue will be removed from queue, and the first index pointer from queue will be moved to the next index. If works, returns the 'dequeued' value, otherwise returns undef.

show()

Try to show the content of queue(the data). This is made finding the 'first' and 'last' pointers, extracting the sequential index, and interate the queue with this indexes, making a 'get' operation from Memcached. If the value exists, it will be showed. If not, a exception will be thrown .

cleanup()

Cleanup everything!

save($parameters)

WARNING! THIS IS A INTERNAL METHOD!

Try to save queue pointers on Memcached. The parameters came on arrayref, when each position of arrayref is a name of attribute that must be saved. This parameters are validated and then saved on memcached.

That makes the enqueuing process faster than save all parameters everytime, because the input operations on Memcached are reduced.

Ex: $q->save(['name','first']);

The valid parameters are:

name - Is the name of Queue;
first - Is the first index of the key. Not the value, but the name of index;
last - As the same way, this is the last index of the queue.

If everything work well the method returns true. Otherwise returns false.

AUTHOR

Andre Garcia Carneiro, <bang at cpan.org>

BUGS

Please report any bugs or feature requests to bug-cache-memcached-queue at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Cache-memcached-Queue. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Cache::Memcached::Queue

You can also look for information at:

TODO

Test all stuff with threads.

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.