Tie::Queue - Introduction
      Tie::Queue - Tie an ARRAY over a TokyTyrant  DB ( see http://tokyocabinet.sourceforge.net )

SYNOPSIS
      use Tie::Queue;
      use Data::Dumper;

      ## Queue creation
      # This queue is not re-initialised at each execution of the script
      # the default namespace is 'Tie-Queue'
      # and each item are non serialized 
      tie my @a, 'Tie::Queue', '127.0.0.1', 1978, 0;

      # This queue is NOT re-initialised at each execution of the script
      # and each item are non serialized 
      # the namespace is 'second_queue'
      tie my @b, 'Tie::Queue', '127.0.0.1', 1978, 1 , 0 , 'second_queue';

      ## put some data in the queue
      for ( 101 .. 110 )
      {
          push @a, $_;
      }

      for ( 1001 .. 1005 )
      {
          push @ab, $_;
      }

      push @b, 'some text';
      push 
      ## show the content of the queue
      print Dumper( \@a );
      ## print the size of the queue
      print "size of array=". scalar @a. "\n";
      ## remove the latest pushed element from the queue ( the newest)
      $res1 = pop @a;
      print  "latest element $res1\n";
      print "size of array=". scalar @a. "\n";
      print Dumper( \@a );
      $res2 = $a[3];
      print  "element 3 = $res2\n";
      ## remove the first element from the queue ( the oldest )
      $res3 = shift @a;
      print  "first element $res3\n";
      print "size of array=". scalar @a. "\n";
      print Dumper( \@a );
      if ( exists $a[4] )
      {
          print "elem 4 exists\n";
      }
      else
      {
          print "elem 4 NOT exists\n";
      }

      if ( exists $a[40] )
      {
          print "elem 40 exists\n";
      }
      else
      {
          print "elem 40 is NOT existing\n";
      }


      (tied @a)->CLEAR;
      print "size of array=". scalar @a. "\n";

      ########################
      # this queue is re-initialised at each execution of the script
      # and each item are serialized 
      # and the name space is 'third_queue_serialized'
      tie my @c, 'Tie::Queue', '127.0.0.1', 1978, 1 , 1 , 'third_queue_serialized';
      my %test = ( a => 'key_a', b => 'key_B' , c => 3 );
      print Dumper(\%test);
      push @d , \%test;
      my $r = pop @d;
      print Dumper($r)
      #######################

DESCRIPTION
      Tie an ARRAY over a TokyTyrant DB and allow to push, pop shift  data;
  
      This module require TokyoTyrant (database and perl module.)
      If the serialisation is required, the module Data::Serilizer is also required
  
      The normal ARRAY function present are
  
      push
      pop
      shift
      exists
      scalar
      storesize ( to allow undef @a)
  
      Specific function
  
      CLEAR
      SYNC
      REPAIR
  
      The following function are not implemented.
  
      EXTEND
      STORE
      DELETE
      SPLICE

Basic functions
    * only the queue relevant functions are present *

  tie
            Tie an array over a DB
            my $t = tie( my @myarray, "Tie::Queue", '127.0.0.1', 1978, 1 , 1 , 'first_name' ,  1 , 0 );
        
            Six optional parameter are allowed
                1) the IP where the TokyoTyrant is running ( default 127.0.0.1 )
                2) the port on which the TokyoTyrant is listenning ( default 1978 )
                3) a flag to delete at start the DB ( default 0 )
                4) a flag to serialize/deserialize on the fly the data stored in the DB
                5) a namespace to allow more than one queue on the same DB ( default Tie-Queue )
                6) a flag to activate or deactivate auto_sync ( default 1 )
                7) a flag to prevent undef value to be pushed ( default 0 )
                8) a flag to use self-healing feature or reset a queue if the data queue is corrupted ( default 0 )
                9) a flag to add some debug info on correctable error ( default 0 )
               10) a flag to prevent insertion of duplicate value ( default 0 )

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

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

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

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

  FETCH
            Retrieve a specific element from the array
            my $data = $myarray[6];

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

  SYNC
            Force a sync of the DB ( not usefull is auto_sync is on)
            $t->SYNC;

  CLEAR
            Delete all element in the array
            $t->CLEAR;

  DESTROY
            Normal destructor call when untied the array
            Normaly never called by user

  REPAIR
            Force a rescan of all elements in the queue and recreate the right indexes

Functions not Implemented
    * Most of then are not related to a QUEUE *

  UNSHIFT
            Not implemented

  EXTEND
            Not implemented

  STORE
            Not implemented

  STORESIZE
            to  resize the array ( this allow a re-initialisation of the array by undef @a )

  DELETE
            Not implemented

AUTHOR
            Fabrice Dulaunoy <fabrice_at_dulaunoy_dot_com>

SEE ALSO
            - TokyoTyrant from Mikio Hirabayashi <mikio_at_users_dot_sourceforge_dot_net>

TODO
            - make test

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::Queue  Copyright (C) 2009 DULAUNOY Fabrice  
            Tie::Queue 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;