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

NAME

Cache::Memcached::Queue - Simple and elegant way to persist queues on Memcached

VERSION

Version 0.1.7

unstable version

DESCRIPTION

The idea is take advantage from Cache::Memcached::Fast module using it as a back-end for queue structures without sockets, extra protocols or extra databases to maintain queues-metadata. All stuff is stored on Memcached! Including metadata.

This can be done adding some metadata on Memcached hash structure that controls data on a queue structure(strict FIFO). This metadata defines identification for queues and controls first element, last element, size(number of elements) and lock information following patterns in their names. For stabilish this patterns, it's necessary to define some elements:

  • prefix - This is defined by the 'id_prefix' attribute. Is the real 'name' of queue. Default value is 'CMQID_'.

  • name - This is a 'string' that defines a name for your queue;

  • id - It's a unique identifier for your queue and is defined on the 'id' attribute. You can have queues with the same name since you have different ids;

  • index - Single sequencial number that identifies a position of some element on queue. For example: 'CMQID_1_1' This is the first element from queue 'CMQID' with id 1. OBS: 'CMQID_1_1' is the same element pointed by 'CMQID_1_first'.

SYNOPSIS

use common::sense;
use Cache::Memcached::Queue;
my $q = Cache::Memcached::Queue->new(   
        name => 'foo', 
        id => 1,
        servers => ['localhost:11211'], #This is default. RTFM ON Cache::Memcached::Fast for more options
        serialize => 1, #if true, every value on enq will be serialized (Data::Serializer with Storable)
                        #but if complex data is passed(hashes, arrays, objects, etc), this data will be
                        #serialized even serialize attribute is false.
       );  


#loading queue  
$q->load();#load data from Memcached

#common operations...
$q->enq('fus'); #enqueue 'fus'. 

$q->enq('goh'); #enqueue 'goh' and this never expires on memcached 

$q->show; #show all items from queue. In this case: 'goh'. Remember... FIFO(First In First Out).

$q->deq; #deqeue 'fus'. 

$q->show; #show all items from queue. In this case: 'nuke'(first and last element from queue).

$q->enq({'fus'=>['goh','dah']}); #enqueue serialize and compact data.

$q->cleanup; #cleans everything. From object and from Memcached.

load()

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

enq( HashRef $parameters or SCALAR $value )

Try to make a 'enqueue' operation. You can enqueue scalar or complex data(hashes, arrays, objects etc).

There is two ways to enqueue:

  • common way(RECOMMENDED):

    my $Bar = 'Bar';
my @Array = ('Foo','Bar');
my %Hash = ('Foo' => 'Bar');
$q->enq('Foo');
$q->enq($Bar);
$q->enq(\@MyArray);
$q->enq(\%MyHash); #since %MyHash doesn't have 'value' and/or 'serialize' as an hash key. This is not treated by module! 
$q->enq({ some => [{complex => 'data'}],}, 
  );

Hashes and Arrays must be passed as a reference! ALWAYS!

  • alternative way(NOT RECOMMENDED):

    $q->enq({value => 'Foo'});
$q->enq({value => $Bar});
$q->enq({value => \@MyArray});
$q->enq({value => \%MyHash}); 
$q->enq({value => { some => [{complex => 'data'}],} );

If you try to enqueue complex data, it will be serialized. Doesn't matter if serialize attribute or parameter is set to false.

If you want to use alternative way, you must know the following valid parameters:

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).

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

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

You can change serialize parameters setting 'serializer' method too.

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.

There is no parameters

Example:

my $first_element_of_queue = $q->deq;

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 .

There is no parameters

Example:

say $q->show;

cleanup()

Dequeue everything! No parameters! Returns true, if it's all right! Otherwise, returns false/throws an exception

save( ArrayRef $parameters )

Internal method to save the queue metadata.

iterate(CODE $action, Array $action_params)

That method is a 'handler'. You can treat all values in another subroutine/static method, passing two parameters:

  • action: this parameter MUST be a CODE reference. Example:

    #EX1: $q->iterate( 
sub {   
 my ($index,$value,$params) = @_;
 #do something with this!!!
}

#EX2: $q->iterate( \&somesubroutine,$myparams) ;
sub somesubroutine {
  my ($index,$value,$params) = @_;
  #do something cool!
}

  • action_params: This can be a custom parameters. All yours!

So, by default, every index and values that are in your queue are passed together with your customized parameters.

If you pass everything right, your 'action' will be performed! Otherwise, an exception will be throwed.

AUTHOR

Andre Garcia Carneiro, <bang at cpan.org>

BUGS

The queue lost reference to last element when there is more than one process accessing queue. I'm working on it.

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.

NOTES FOR THIS VERSION

  • 'beta' version was change to 'unstable', because multi-processing access is not working well yet.

  • The auto-installer was removed after CPAN request.

  • 'servers' attribute have ['localhost:11211'] as default value;

  • 'serialize' attribute is DEPRECATED. Doesn't work anymore;

  • The new method 'iterator' allows delegate to other subroutine/static method queue data;

  • 'lock' feature is a internal feature that allows have a same queue with multiple processes working on it. (EXPERIMENTAL)

  • 'init' method was removed!

TODO

  • performance optimization

  • 'priority' support, maybe

SUPPORT

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

perldoc Cache::Memcached::Queue

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2013 2014 Andre Garcia Carneiro.

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.