|o||Writer1: calls the add() method|
|o||Writer2: calls the add() method|
|o||Writer2: the add() method returns|
|o||Writer1: the add() method returns|
For simplicity, this implementation provides only best effort FIFO, i.e. there is a very high probability that elements are processed in FIFO order but this is not guaranteed. This is achieved by using a high-resolution timer and having elements sorted by the time their final directory gets created.
Different queue types are supported. More detailed information can be found in the modules implementing these types:
Compared to Directory::Queue::Normal, Directory::Queue::Simple:
o Directory::Queue::Normal o Directory::Queue::Simple o Directory::Queue::Null
Directory::Queue::Null is special: it is a kind of black hole with the same API as the other directory queues.
o is simpler o is faster o uses less space on disk o can be given existing files to store o does not support schemas o can only store and retrieve binary strings o is not compatible (at filesystem level) with Directory::Queue::Normal
Adding an element is not a problem because the add() method is atomic.
In order to support multiple reader processes interacting with the same queue, advisory locking is used. Processes should first lock an element before working with it. In fact, the get() and remove() methods report a fatal error if they are called on unlocked elements.
If the process that created the lock dies without unlocking the element, we end up with a staled lock. The purge() method can be used to remove these staled locks.
An element can basically be in only one of two states: locked or unlocked.
A newly created element is unlocked as a writer usually does not need to do anything more with it.
Iterators return all the elements, regardless of their states.
There is no method to get an element state as this information is usually useless since it may change at any time. Instead, programs should directly try to lock elements to make sure they are indeed locked.
The new() method of this module can be used to create a Directory::Queue object that will later be used to interact with the queue. It can have a type attribute specifying the queue type to use. If not specified, the type defaults to Simple.
This method is however only a wrapper around the constructor of the underlying module implementing the functionality. So:
$dirq = Directory::Queue->new(type => Foo, ... options ...);
is identical to:
$dirq = Directory::Queue::Foo->new(... options ...);
Regardless of how the directory queue object is created, it inherits from the Directory::Queue class. You can therefore test if an object is a directory queue (of any kind) by using:
if ($object->isa("Directory::Queue")) ...
Here are the methods available in the base class and inherited by all directory queue implementations:
new(PATH) return a new object (class method) copy() return a copy of the object path() return the queue toplevel path id() return a unique identifier for the queue first() return the first element in the queue, resetting the iterator; return an empty string if the queue is empty next() return the next element in the queue, incrementing the iterator; return an empty string if there is no next element touch(ELEMENT) update the elements access and modification times to indicate that it is still being used
There are no specific security mechanisms in this module.
The elements are stored as plain files and directories. The filesystem security features (owner, group, permissions, ACLs...) should be used to adequately protect the data.
By default, the process umask is respected. See the class constructor documentation if you want an other behavior.
If multiple readers and writers with different uids are expected, the easiest solution is to have all the files and directories inside the toplevel directory world-writable (i.e. umask=0). Then, the permissions of the toplevel directory itself (e.g. group-writable) are enough to control who can access the queue.
Lionel Cons <http://cern.ch/lionel.cons>
Copyright (C) CERN 2010-2013
|perl v5.20.3||DIRECTORY::QUEUE (3)||2013-05-21|