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

Provided by: libfile-queue-perl_1.01a-2_all

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.

• new()

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

• enq()

Enqueues a string element to the queue.

• deq()

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

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

• reset()

Emptys the queue.

• close()

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

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

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

• Mode (optional)

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

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

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

AUTHOR