/ 
File-Queue-1.01a
River stage zero No dependents
/ File::Queue

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!

SEE ALSO

Tie::File

AUTHOR

Jason Lavold <jlavold [ at ] gmail.com>