NAME

Queue::Dir - Manage queue directories where each object is a file

SYNOPSIS

  use Queue::Dir;

  my $q = new Queue::File (
                           -id => $my_process_id,
                           -paths => [ '/var/path/to/queue1', ... ],
                           -promiscuous => 1,
                           -sort => 'sortsub',
                           -filter => sub { ... },
                           -lockdir => 'lock',
                           -lockmax => 300,
                           );
  
  my ($fh, $qid) = $q->store($oid);

  my $qid = $q->next();

  my $fh = $q->visit($mode, $qid);

  my $status = $q->done($qid);

  my $name = $q->name($qid);

DESCRIPTION

Queue::Dir allows the manipulation of objects placed in a queue. The queue is implemented as a directory where each object is stored as a file.

METHODS

The following methods are defined:

my $q = new Queue::File (...)

-id assigns a unique process-id to this queue object. Defaults to something built from the serialization of the object + $$ or something similar.

-paths specifies a list of paths to use as storage points for the queue files. If more than one are supplied, round-robin will be used to store objects there.

When -promiscuous is true (the default), objects stored with any other Queue::File object are accessible. If set to false, only files whose id matches the value for -id are visible.

-sort allows for the specification of a sorting function, used to decide the order in which the queue files will be used. The function is invoked in the same fashion as sort, getting two variables ($a and $b) and returning -1, 0 or 1 depending on comparison. $a and $b are hash references whose first element is the queue id of the object and the second element is a the full pathname of such object.

The sub { ... } passed in the -filter parameter can control which files in a given directory to consider as queue objects. By default, all files will be considered part of the queue. This function is called with a reference of the invoking object and the full pathname of each file. A true return value causes the given file to be included in the queue. Note that this is only called if -promiscuous is set to a false value.

-lockdir and -lockmax control an optional locking mechanism that reduces the chance of multiple collaborating instances of Queue::Dir objects, from picking the same object from the queue. -lockdir, when present, defines the name of the directory (within each queue directory) to use for storing the lock files. The -lockmax parameter, which defaults to 300 seconds, control for how long the locks are honored.

Note that locking is disabled by default.

my ($fh, $qid) = $q->store();

Store a file in the queue. Returns an array whose first element is an IO::Handle object for writing to the file. The second element is the identifier of the object in the queue.

If you created the Queue::Dir object with locking enabled, you must call ->unlock after closing the file handle.

my $qid = $q->next();

Returns the queue identifier of the next file to be processed. When the queue is empty, returns undef.

Note that if multiple consumers are working on the same queues in promiscuous mode, the file referenced by the returned id might be removed at any time so care must be used.

Entries will be returned in an arbitrary order.

my $fh = $q->visit($mode, $qid);

On success, returns an IO::Handle object, opened according to the specified $mode for the file with $qid. If $mode is not specified, it defaults to a read from the start of the file. If $qid is not specified, it defaults to the next entry, as if ->next() were called. In order for the file to be eligible, either the Queue::Dir object is not created with locking enabled or the file in the queue is not locked.

It can fail in a number of situations. The obvious one, is when the queue is empty. The second one, happens when the desired file is no longer in the queue, which can happen if multiple consumers are accessing the queue in promiscuous mode.

To help disambiguate both scenarios, undef will be returned on an empty queue. A defined but false value will be returned when the desired file is missing but others remain in the queue.

The object in the queue will be automatically locked if this option is enabled when ->new was called. In this case, you should call the ->unlock method.

$q->done($qid);

Disposes the queue file whose $qid matches the given identifier as well as its potential lock. If none is specified, defaults to the last one used in a ->visit().

It is a bad idea (or at least rough manners) to unlink() the file without invoking ->done. Besides, ->done will do it for you.

my $fname = $q->name($qid);

Returns the full pathname of the queue file whose id matches $qid. If none is supplied, defaults to the last one obtained through a ->store(), ->next() or ->visit().

It could return undef is the queue object no longer exists.

->unlock($qid)

Removes any locks outstanding in the file identified by $qid, or the last visit()ed file. Use of this method is only required if the object is created with locking enabled.

EXPORT

None by default.

HISTORY

$Id: Dir.pm,v 1.13 2003/03/09 16:18:48 lem Exp $

$Log: Dir.pm,v $ Revision 1.13 2003/03/09 16:18:48 lem Added more fixes for lock()/unlock(). We should not lose locks provided a working flock()

Revision 1.12 2003/01/19 15:01:09 lem Added fcntl(LOCK_UN) to unlock() to free the lock

Revision 1.11 2002/12/09 22:53:58 lem Added flock() locking in addition to our own locking scheme

Revision 1.10 2002/12/09 22:36:34 lem ->visit() has better decoupling. Added some tests

Revision 1.9 2002/12/08 04:23:05 lem ->visit must return an object as soon as available. Added tests for this too.

Revision 1.8 2002/12/08 01:00:18 lem Added locking + tests

0.01

Original version; created by h2xs 1.2 with options

  -ACOXcfkmn
        Queue::Dir
        -v
        0.01

AUTHOR

Luis E. Muñoz <luismunoz@cpan.org>

SEE ALSO

perl(1).