/ 
Cache-Memcached-PDeque-0.01
River stage zero No dependents
/ Cache::Memcached::PDeque

NAME

Cache::Memcached::PDeque - Implements a priority deque using memcached as storage

VERSION

Version 0.01

SYNOPSIS

use Cache::Memcached::PDeque;

# Create a PDeque with a priorities 1 and 2
my $dq = Cache::Memcached::PDeque->new( name => 'aName', max_prio => 2 );

# Add and remove some elements
$dq->push('a');    # ('a')
$dq->unshift('b'); # ('b','a')
$dq->push('c');    # ('b','a','c')

$dq->pop();       # returns 'c'
$dq->pop();       # returns 'a'
$dq->shift();     # returns 'b'

# Make use of priorities
$dq->push_with_priority(1,'l1'); # ('l1')
$dq->push_with_priority(1,'l2'); # ('l1','l2')
$dq->push_with_priority(2,'h1'); # ('h1','l1','l2')
$dq->push_with_priority(1,'l3'); # ('h1','l1','l2','l3')
$dq->push_with_priority(2,'h2'); # ('h1','h2','l1','l2','l3')

$dq->shift();     # returns 'h1'
$dq->shift();     # returns 'h2'
$dq->shift();     # returns 'l1'
$dq->shift();     # returns 'l2'
$dq->shift();     # returns 'l3'

# Complex structures are supported
my @list = ( 1, 'a', 2, 'b', 3, 'c' );
$dq->push(\@list);   # Push reference to a list
my $href = $dq->pop; # Get back reference to a list

DESCRIPTION

This is an implementation of a double-ended queue, with support for priorities.

A double-ended queue, abbreviated to deque, is an abstract data type that combines the functionality of a queue and a stack, allowing elements to be added to, and removed from, both the front and the back.

In addition, this implementation adds support for associating a priority with an element, making it possible to serve elements with a higher priority before elements with a lower priority.

The storage backend for this implementation is Memcached, an in-memory key-value store for small chunks of arbitrary data (strings, objects). Cache::Memecached::Fast is used to access to Memcached.

METHODS

CONSTRUCTOR

my $dq = Cache::Memcached::PDeque->new( 
                              name => 'aName',
                              max_prio => 1,
                              prioritizer => undef,
                              servers => [ '127.0.0.1:11211' ],
                          );

Create new PDeque object.

name

Set the name of the dqueue; is a required argument. This will be part of the prefix used in Memcached. Is should be unique.

max_prio

Sets the maximum priority for this dqueue. Must be a value in the range [1..10]. Defaults to 1.

prioritizer

A reference to a subroutine that must return a priority in the range [1..max_prio]. It is called for each element that is added by either push() or unshift(). The default is 'undef', which uses the lowest priority '1' for 'push' and the highest priority 'max_prio' for unshift.

my $dqr = Cache::Memcached::PDeque->new( name => 'aName', 
                                         max_prio => 2,
                                         prioritizer => \&remainder ); 

sub remainder {
  my $element = shift;
  my $prio = $element % 2; # This is either 0 or 1
  return $prio+1;          # This is 1 or 2, a valid priority
}

$dqr->push(1); # ( 1 )
$dqr->push(2); # ( 1 2 )
$dqr->push(3); # ( 1 3 2 )
$dqr->shift;   # returns 1
$dqr->shift;   # returns 3
$dqr->shift;   # returns 2

servers

A list of Memcached servers to connect to. Defaults to '127.0.0.1:11211'.

METHODS

The following public methods are available.

Please note that any methods starting with an underscore '_' are considered private, are undocumented, and are subject to change without notice. Do not use private methods.

size

my $size = $dq->size;

Returns the number of elements in $dq.

push_with_priority

$dq->push_with_priority($priority, $element);

Adds $element after all elements with a higher or equal priority, and before all elements with a lower priority.

push

$dq->push($element);

Adds $element after all elements.

unshift_with_priority

$dq->unshift_with_priority($priority, $element);

Inserts $element after all elements with a higher priority, and before all elements with a lower or equal priority.

unshift

$dq->unshift($element);

Insert $element before all elements.

pop_with_priority

my $element = $dq->pop_with_priority($priority);

Returns the last element with the given priority.

pop

my $element = $dq->pop;

Returns the last element.

shift_with_priority

my $element = $dq->shift_with_priority($priority);

Returns the first element with the given priority.

shift

my $element = $dq->shift;

Returns the first element.

foreach

sub do_something {
  my $el = shift;
  print "square of $el is " . $el ** 2 . "\n";
}

$dq->foreach(\&do_something);

Executes a subroutine on every element.

(!) Do not attempt to modify $dq from within the do_something() subroutine. This will cause a deadlock.

AUTHOR

Peter Haijen, <peterhaijen at cpan.org>

BUGS

Please report any bugs or feature requests to bug-cache-memcached-pdeque at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Cache-Memcached-PDeque. 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::PDeque

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2024 by Peter Haijen.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)