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

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
  
      The following function is not completely iplemented.
  
      splice
  
      The following function are not implemented.
  
      extend
      store
      unshift
      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)
            A second optional parameter allow to set the permission in octal of the DB created
            The default permisscion is 0600 (-rw-------) 
      
  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 in the array 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;
      
  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;
    =cut

    sub OPTIMIZE { my $self = shift; my ( $lmemb, $nmemb, $bnum, $apow,
    $fpow, $opts ) = ( @_ ); my $bdb = $self->{ _bdb }; $bdb->optimize(
    $lmemb, $nmemb, $bnum, $apow, $fpow, $opts ); chmod $self->{ _mode },
    $self->{ _file }; }

Functions not Implemented
    * *

  EXTEND
            Not implemented because not signifiant for a expiration queue
        
  STORE
            Not implemented because not signifiant for a expiration queue
        
  UNSHIFT
            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;