NAME

Thread::Queue::Priority - Thread-safe queues with priorities

VERSION

This document describes Thread::Queue::Priority version 1.03

SYNOPSIS

    use strict;
    use warnings;

    use threads;
    use Thread::Queue::Priority;

    # create a new empty queue
    my $q = Thread::Queue::Priority->new();

    # add a new element with default priority 50
    $q->enqueue("foo");

    # add a new element with priority 1
    $q->enqueue("foo", 1);

    # dequeue the highest priority on the queue
    my $value = $q->dequeue();

DESCRIPTION

This is a variation on Thread::Queue that will dequeue items based on their priority. This module is NOT a drop-in replacement for Thread::Queue as it does not implement all of its methods as they don't all make sense. However, for the methods implemented and described below, consider the functionality to be the same as that of Thread::Queue.

QUEUE CREATION

->new()

Creates a new empty queue. A list cannot be created with items already on it.

->enqueue(ITEM, PRIORITY)

Adds an item onto the queue with the givern priority. Only one item may be added at a time. If no priority is given, it is given a default value of 50. There are no constraints on the priority number with the exception that it must be greater than zero and it must be a number. The smaller the number, the greater the priority.

->dequeue()

->dequeue(COUNT)

Removes and returns the requested number of items (default is 1) in priority order where smaller numbers indicate greater priority. If the queue contains fewer than the requested number of items, then the thread will be blocked until the requisite number of items are available (i.e., until other threads <enqueue> more items).

->dequeue_nb()

->dequeue_nb(COUNT)

This functions the same as dequeue but it will not block if the queue is empty or the queue does not have COUNT items. Instead it will return whatever is on the queue up to COUNT, or undef if the queue is empty. Again, items will come off the queue in priority order where smaller numbers have a higher priority.

->dequeue_timed(TIMEOUT)

->dequeue_timed(TIMEOUT, COUNT)

This functions the same as dequeue but will only block for the length of the given timeout. If the timeout is reached, it returns whatever items there are on the queue, or undef if the queue is empty. Again, items will come off the queue in priority order where smaller numbers have a higher priority.

The timeout may be a number of seconds relative to the current time (e.g., 5 seconds from when the call is made), or may be an absolute timeout in epoch seconds the same as would be used with cond_timedwait(). Fractional seconds (e.g., 2.5 seconds) are also supported (to the extent of the underlying implementation).

If TIMEOUT is missing, undef, or less than or equal to 0, then this call behaves the same as dequeue_nb.

->pending()

Returns the number of items still in the queue. Returns undef if the queue has been ended (see below), and there are no more items in the queue.

->end()

Declares that no more items will be added to the queue.

All threads blocking on dequeue() calls will be unblocked with any remaining items in the queue and/or undef being returned. Any subsequent calls to dequeue() will behave like dequeue_nb().

Once ended, no more items may be placed in the queue.

->peek(INDEX)

Returns n item from the queue without dequeuing anything. Defaults to the the head of queue (at index position 0) if no index is specified. Negative index values are supported as with arrays (i.e., -1 is the end of the queue, -2 is next to last, and so on).

If no items exists at the specified index (i.e., the queue is empty, or the index is beyond the number of items on the queue), then undef is returned.

Remember, the returned item is not removed from the queue, so manipulating a peeked at reference affects the item on the queue.

SEE ALSO

Thread::Queue, threads, threads::shared

MAINTAINER

Paul Lockaby <plockaby AT cpan DOT org>

CREDIT

Significant portions of this module are directly from Thread::Queue which is maintained by Jerry D. Hedden, <jdhedden AT cpan DOT org>.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.