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

NAME

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

VERSION

Version 0.03

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->front;       # returns 'b' without altering $dq
$dq->back;        # returns 'c' without altering $dq

$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

# A oneliner to copy all elements to a simple list
my @dq;
$dq->foreach( sub { my ($e, $p) = @_; push @{$p}, $e }, \@dq);

# 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

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.

CONSTRUCTOR

my $dq = Cache::Memcached::PDeque->new( 
                              name => 'aName',
                              max_size => 0,
                              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_size

The maximum number of allowed elements, 0 for unlimited. Defaults to 0.

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

clear

$dq->clear;

Removes all elements.

max_size

$dq->max_size(25);

Set the maximum number of elements that are allowed.
Setting max_size to '0' (the default) means no limit, and is faster then setting it to a (very) high number.
Setting the max_size lower than the current size does not remove any elements.

my $max = $dq->max_size();

Get the current maximum number of elements allowed; returns 0 for unlimited.

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.

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

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

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.

front

my $element = $dq->front;

Returns the first element, without removing it from the PDeque.

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

Returns the first element with the given priority, without removing it from the PDeque.

back

my $element = $dq->front;

Returns the last element, without removing it from the PDeque.

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

Returns the last element with the given priority, without removing it from the PDeque.

foreach

sub do_square {
  my ( $el, $param ) = @_;
  push @{$param}, $el**2;
}

my @squared;
$dq->foreach(\&do_square, \@squared);

Executes a subroutine on every element. In the example, for each element in $dq, calculate the square
value and push that onto @squared.

(!) Do not attempt to modify $dq from within the do_square() 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)