Tie::Array::QueueExpire - Introduction Tie::Array::QueueExpire - Tie an ARRAY over a TokyCabinet Btree DB ( see http://tokyocabinet.sourceforge.net ) Revision: 1.01 SYNOPSIS use Tie::Array::QueueExpire; my $t = tie( my @myarray, "Tie::Array::QueueExpire", '/tmp/db_test.bdb' ); push @myarray, int rand 1000; # normal ARRAY function my $data = shift @myarray; my $data = pop @myarray; print "this elem exists\n" if (exists( $myarray[6])); print "size = ". scalar( @myarray )."\n"; # using the PUSH with an extra parameter to put the new element in futur # also return the key of the inserted value for ( 1 .. 10 ) { say "t=".time.' '. int (($t->PUSH( $_ . ' ' . time, 10 ))/1000); sleep 1; } sleep 10; # Get the expired elements ( 7 seconds before now ) my $ex = $t->EXPIRE( 7 ); # Get the expired elements my @EXP = @{$t->EXPIRE($exp)}; # Get and delete the expired elements ( 20 seconds before now ) $ex = $t->EXPIRE(20,1); my @EXP = @{$t->EXPIRE($exp,1)}; # fetch element # in scalar context return the value # in array context return in first element the key and in second, the value my $a =$t->FETCH(6); my @b = $t->FETCH(6); # the normal array fetch is always in scalar mode my @c=$myarray[6]; say Dumper( $a ); say Dumper( \@b ); say Dumper( \@c ); DESCRIPTION Tie an ARRAY over a TokyCabinet Btree DB and allow to get or deleted expired data; This module require Time::HiRes, TokyoCabinet (database and perl module.) The insertion is ms unique ( 0.001 seconds ) The normal ARRAY function present are push pop shift exits scalar clear unshift (but put data 1 second before the first entry) The following function is not completely iplemented. splice The following function are not implemented. extend store STORESIZE The following function are specific of this module. LAST FIRST EXPIRE OPTIMIZE PUSH FETCH Basic ARRAY functions * * tie Tie an array over a TokyoCabinet DB my $t = tie( my @myarray, "Tie::Array::QueueExpire", '/tmp/db_test.bdb' ); The fist parameter if the TokyoCabinet file used (or created) Four optional parameter are allowed In place two, a flag to serialize the data in the DB In place three, an octal MASK allow to set the permission of the DB created The default permission is 0600 (-rw-------) In place four a parameter to delete the DB file if present and corrupted The default value is 0 (don't delete the file) In place five a parameter to exit on error when opening the DB file The default value is 0 (don't exit, only report error) FETCH Retrieve a specific key from the array my $data = $myarray[6]; or my $data = $t->FETCH(6); or my @data = $t->FETCH(6); where $data[0] = insertion key and $data[1] = value FETCHSIZE Get the size of the array my $data = scalar(@myarray); PUSH Add an element at the end of the array push @myarray , 45646; or $t->PUSH( 45646 ); it is also possible to add an elemnt with a offset expiration $t->PUSH( 45646 , 10 ); add element in the array to be expired in 10 seconds if the offset is negative, add the expiration in past EXISTS Test if en element in the array exist print "element exists\n" if (exits $myarray[5]); return the insertion key POP Extract the latest element from the array (the youngest) my $data = pop @myarray; or my $data = $t->POP(); or my @data = $t->POP(); where $data[0] = insertion key and $data[1] = value SHIFT Extract the first element from the array (the oldest) my $data = shift @myarray; or my $data = $t->SHIFT(); or my @data = $t->SHIFT(); where $data[0] = insertion key and $data[1] = value UNSHIFT Add an element in the front of the array unshift @myarray , 45646; UNSHIFT data 1 mili-second before the first item CLEAR Delete all element in the array $t->CLEAR; DESTROY Normal destructor call when untied the array Normaly never called by user Specific functions from this module * * SPLICE SPLICE don't allow a list replacement because the insert order is made by time. my @tmp = splice @myarray, 5 ,3; LAST Get the latest element in the array (oldest) my $data = $t->LAST; or my @data = $t->LAST; where $data[0] = insertion key and $data[1] = value FIRST Get the first element in the array (youngest) my $data =$t->FIRST; or my @data = $t->FIRST; where $data[0] = insertion key and $data[1] = value EXPIRE Get the elements expired in the array. my @ALL = $t->EXPIRE( 1207840028) ; return a refernce to an array with all the expired value. If a second parameter is provided and not null, the data are also deleted from the array. my @ALL = $t->EXPIRE( 1207840028 , 1 ) ; return a refernce to an array with all the expired value. OPTIMIZE Function to compact the DB (after a lot of delete ) $t->OPTIMIZE; Functions not Implemented * * EXTEND Not implemented because not signifiant for a expiration queue STORE Not implemented because not signifiant for a expiration queue STORESIZE Not implemented because not signifiant for a expiration queue AUTHOR Fabrice Dulaunoy SEE ALSO - Data::Queue::Persistent from Mischa Spiegelmock, - TokyoCabinet from Mikio Hirabayashi TODO - make test - implementation of EXTEND to allow clear of array with @myarray = (); - implementation of STORESIZE to allow clear of array with $#myarray = -1; LICENSE Under the GNU GPL2 This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Tie::Array::QueueExpire Copyright (C) 2004 2005 2006 2007 2008 2009 2010 DULAUNOY Fabrice Tie::Array::QueueExpire comes with ABSOLUTELY NO WARRANTY; for details See: L This is free software, and you are welcome to redistribute it under certain conditions;