Tie::Array::QueueExpire - Introduction

  Tie::Array::QueueExpire - Tie an ARRAY over a TokyCabinet Btree DB ( see http://tokyocabinet.sourceforge.net )
  $Revision: 55 $

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";
  
  
  my $exp = 1207840028;
  # Get the expired elements
  my @EXP = @{$t->EXPIRE($exp)};
  # Delete the expired elements
  my @EXP = @{$t->EXPIRE($exp,1)};

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

Basic ARRAY functions

tie

        Tie an array over a 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 permisscion 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];

FETCHTIME

        Retrieve a specific key from the array with the TIME tag
        my ($data, $ticks) = $t->FETCHTIME(6);

FETCHSIZE

        Get the size of the array
        my $data = scalar(@myarray);

PUSH

        Add an element at the end of the array
        push @myarray , 45646;

EXISTS

        Test if en element in the array exist
        print "element exists\n" if (exits $myarray[5]);

POP

        Extract the latest element from the array (the youngest)
        my $data = pop @myarray;

SHIFT

        Extract the first element from the array  (the oldest)
        my $data = pop @myarray;

UNSHIFT

        Add an element in the front of the array
        unshift @myarray , 45646;
        UNSHIFT data 1 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;

FIRST

        Get the first element in the array (youngest)
        my $data =$t->LAST;

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 <fabrice_at_dulaunoy_dot_com> 

SEE ALSO

        - Data::Queue::Persistent from Mischa Spiegelmock, <mspiegelmock_at_gmail_dot_com>
        - TokyoCabinet from Mikio Hirabayashi <mikio_at_users_dot_sourceforge_dot_net>

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 DULAUNOY Fabrice  
        Tie::Array::QueueExpire comes with ABSOLUTELY NO WARRANTY; 
        for details See: L<http://www.gnu.org/licenses/gpl.html> 
        This is free software, and you are welcome to redistribute 
        it under certain conditions;