NAME

threads::shared::queue::any - thread-safe queues for any data-structure

SYNOPSIS

    use threads::shared::queue::any;
    my $q = threads::shared::queue::any->new;
    $q->enqueue("foo", ["bar"], {"zoo"});
    my ($foo,$bar,$zoo) = $q->dequeue;
    my ($foo,$bar,$zoo) = $q->dequeue_nb;
    my $left = $q->pending;

DESCRIPTION

A queue, as implemented by threads::shared::queue::any is a thread-safe data structure that inherits from threads::shared::queue. But unlike the standard threads::shared::queue, you can pass (a reference to) any data structure to the queue.

Apart from the fact that the parameters to enqueue are considered to be a set that needs to be enqueued together and that dequeue returns all of the parameters that were enqueued together, this module is a drop-in replacement for threads::shared::queue in every other aspect.

Any number of threads can safely add elements to the end of the list, or remove elements from the head of the list. (Queues don't permit adding or removing elements from the middle of the list).

FUNCTIONS AND METHODS

new

The new function creates a new empty queue.

enqueue LIST

The enqueue method adds a reference to all the specified parameters on to the end of the queue. The queue will grow as needed.

dequeue

The dequeue method removes a reference from the head of the queue, dereferences it and returns the resulting values. If the queue is currently empty, dequeue will block the thread until another thread enqueues.

dequeue_nb

The dequeue_nb method, like the dequeue method, removes a scalar from the head of the queue and returns it. Unlike dequeue, though, dequeue_nb won't block if the queue is empty, instead returning undef.

pending

The pending method returns the number of items still in the queue.

CAVEATS

Passing unshared values between threads is accomplished by serializing the specified values using Storable when enqueuing and de-serializing the queued value on dequeuing. This allows for great flexibility at the expense of more CPU usage. It also limits what can be passed, as e.g. code references can not be serialized and therefor not be passed.

SEE ALSO

threads, threads::shared, threads::shared::queue.