.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "File::Queue 3pm" .TH File::Queue 3pm "2008-12-22" "perl v5.10.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" File::Queue \- Persistent FIFO queue implemented in pure perl! .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use strict; # always! \& use File::Queue; \& \& my $q = new File::Queue (File => \*(Aq/var/spool/yourprog/queue\*(Aq); \& \& $q\->enq(\*(Aqsome flat text1\*(Aq); \& $q\->enq(\*(Aqsome flat text2\*(Aq); \& $q\->enq(\*(Aqsome flat text3\*(Aq); \& \& # Get up to first 10 elements \& my $contents = $q\->peek(10); \& \& my $elem1 = $q\->deq(); \& my $elem2 = $q\->deq(); \& \& # empty the queue \& $q\->reset(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module allows for the creation of persistent \s-1FIFO\s0 queue objects. .PP File::Queue only handles scalars as queue elements. If you want to work with references, serialize them first! .PP The module was written with speed in mind, and it is very fast, but it should be used with care. Please refer to the \s-1CAVEATS\s0 section. .SH "Interface" .IX Header "Interface" File::Queue implements a \s-1OO\s0 interface. The object methods and parameters are described below. .SS "Methods" .IX Subsection "Methods" File::Queue supports all of the queue-related functions a developer should expect. .IP "\(bu" 4 \&\fInew()\fR .Sp Instantiates your File::Queue object. Parameters are described in the next sub-section. .IP "\(bu" 4 \&\fIenq()\fR .Sp Enqueues a string element to the queue. .IP "\(bu" 4 \&\fIdeq()\fR .Sp Dequeues a string element from the queue, and returns the element. If the queue is empty, nothing is returned. .IP "\(bu" 4 peek(n) .Sp 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. .IP "\(bu" 4 \&\fIreset()\fR .Sp Emptys the queue. .IP "\(bu" 4 \&\fIclose()\fR .Sp Closes the filehandles belonging to the queue object ('.dat' and '.idx'). .IP "\(bu" 4 \&\fIdelete()\fR .Sp Deletes the files belonging to the queue object ('.dat' and '.idx'). .SS "Parameters" .IX Subsection "Parameters" There are a number of parameters that can be passed when constructing your File::Queue objects. Parameters are case-insensitive. .IP "\(bu" 4 File (required) .Sp File::Queue creates two files using this parameter as the base. In the case of the example in the \s-1SYNOPSIS\s0, the two files are '/var/spool/yourprog/queue.dat' and '/var/spool/yourprog.idx'. .Sp 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. .IP "\(bu" 4 Mode (optional) .Sp The file bit mode to be shared by both the '.dat' and '.idx' files. Defaults to '0600'. .IP "\(bu" 4 Seperator (optional) .Sp The character or byte sequence that is used to seperate queue elements in the '.dat' file. It should be something you can guarantee will \s-1NEVER\s0 appear in your queue data. Defaults to the newline character. .IP "\(bu" 4 BlockSize (optional) .Sp 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. .SH "CAVEATS" .IX Header "CAVEATS" This module should never be used in situations where the queue is not expected to become empty. .PP The '.dat' file is not truncated (emptied) until the queue is empty. .PP Even the data you've already dequeued remains in the '.dat' file until the queue is empty. .PP If you keep enqueueing elements and never \s-1FULLY\s0 dequeue everything, eventually your disk will fill up! .SH "SEE ALSO" .IX Header "SEE ALSO" Tie::File .SH "AUTHOR" .IX Header "AUTHOR" Jason Lavold