The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Tie-Queue-0.19
River stage zero No dependents
++
/ Tie::Queue

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;