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

NAME

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

VERSION

Version 0.02

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->size;        # returns 3

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

# Make use of priorities
$dq->push(1,'l1'); # ('l1')
$dq->push(2,'h1'); # ('h1','l1')

$dq->size;        # returns 2, but:
$dq->size(1);     # returns 1 - only 1 element with priority 1

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

# 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

# Removes all elements
$dq->clear;

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.

clear

$dq->clear;

Removes all elements.

size

my $size = $dq->size;

Returns the number of elements in $dq.

my $size = $dq->size($priority);

Returns the number of elements in $dq with the given priority.

push

$dq->push($element);

Adds $element after all elements.

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

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

unshift

$dq->unshift($element);

Insert $element before all elements.

pop

my $element = $dq->pop;

Returns the last element.

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

Returns the last element with the given priority.

shift

my $element = $dq->shift;

Returns the first element.

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

Returns the first element with the given priority.

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)