/usr/share/perl5/File/Queue.pod is in libfile-queue-perl 1.01a-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | =head1 NAME
File::Queue - Persistent FIFO queue implemented in pure perl!
=head1 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();
=head1 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.
=head1 Interface
File::Queue implements a OO interface. The object methods and parameters are described below.
=head2 Methods
File::Queue supports all of the queue-related functions a developer should expect.
=over
=item * new()
Instantiates your File::Queue object. Parameters are described in the next sub-section.
=item * enq()
Enqueues a string element to the queue.
=item * deq()
Dequeues a string element from the queue, and returns the element. If the queue is empty, nothing is returned.
=item * 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.
=item * reset()
Emptys the queue.
=item * close()
Closes the filehandles belonging to the queue object ('.dat' and '.idx').
=item * delete()
Deletes the files belonging to the queue object ('.dat' and '.idx').
=back
=head2 Parameters
There are a number of parameters that can be passed when constructing your File::Queue objects. Parameters are case-insensitive.
=over
=item * 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.
=item * Mode (optional)
The file bit mode to be shared by both the '.dat' and '.idx' files. Defaults to '0600'.
=item * 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.
=item * 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.
=back
=head1 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!
=head1 SEE ALSO
Tie::File
=head1 AUTHOR
Jason Lavold E<lt>jlavold [ at ] gmail.comE<gt>
=cut
|