File::Queue(3pm)					User Contributed Perl Documentation					  File::Queue(3pm)

NAME

       File::Queue - Persistent FIFO queue implemented in pure perl!

SYNOPSIS

	   use strict; # always!
	   use File::Queue;

	   my $q = new File::Queue (File => '/var/spool/yourprog/queue');

	   $q->enq('some flat text1');
	   $q->enq('some flat text2');
	   $q->enq('some flat text3');

	   # Get up to first 10 elements
	   my $contents = $q->peek(10);

	   my $elem1 = $q->deq();
	   my $elem2 = $q->deq();

	   # empty the queue
	   $q->reset();

DESCRIPTION

       This module allows for the creation of persistent FIFO queue objects.

       File::Queue only handles scalars as queue elements.  If you want to work with references, serialize them first!

       The module was written with speed in mind, and it is very fast, but it should be used with care.  Please refer to the CAVEATS section.

Interface
       File::Queue implements a OO interface.  The object methods and parameters are described below.

   Methods
       File::Queue supports all of the queue-related functions a developer should expect.

       o   new()

	   Instantiates your File::Queue object.  Parameters are described in the next sub-section.

       o   enq()

	   Enqueues a string element to the queue.

       o   deq()

	   Dequeues a string element from the queue, and returns the element.  If the queue is empty, nothing is returned.

       o   peek(n)

	   Returns an arrayref containing the next n elements in the queue.  If the queue size is less than n, all elements are returned.  If the
	   queue is empty, an empty arrayref is returned.

       o   reset()

	   Emptys the queue.

       o   close()

	   Closes the filehandles belonging to the queue object ('.dat' and '.idx').

       o   delete()

	   Deletes the files belonging to the queue object ('.dat' and '.idx').

   Parameters
       There are a number of parameters that can be passed when constructing your File::Queue objects.	Parameters are case-insensitive.

       o   File (required)

	   File::Queue creates two files using this parameter as the base.  In the case of the example in the SYNOPSIS, the two files are
	   '/var/spool/yourprog/queue.dat' and '/var/spool/yourprog.idx'.

	   The '.dat' file holds all of the data, the '.idx' file holds the byte index (pointer) of the starting point of the first element in the
	   queue.

       o   Mode (optional)

	   The file bit mode to be shared by both the '.dat' and '.idx' files.	Defaults to '0600'.

       o   Seperator (optional)

	   The character or byte sequence that is used to seperate queue elements in the '.dat' file.  It should be something you can guarantee
	   will NEVER appear in your queue data.  Defaults to the newline character.

       o   BlockSize (optional)

	   This is the size of the byte chunks that are pulled at each iteration when checking for the end of a queued element.  Defaults to 64,
	   which will be fine for most cases, but can be tweaked or tuned for your specific case to squeeze out a few extra nanoseconds.

CAVEATS

       This module should never be used in situations where the queue is not expected to become empty.

       The '.dat' file is not truncated (emptied) until the queue is empty.

       Even the data you've already dequeued remains in the '.dat' file until the queue is empty.

       If you keep enqueueing elements and never FULLY dequeue everything, eventually your disk will fill up!

SEE ALSO

       Tie::File

AUTHOR

       Jason Lavold <jlavold [ at ] gmail.com>

perl v5.10.0							    2008-12-22							  File::Queue(3pm)