POE::Queue - documentation for POE's priority queue interface

NAME

POE::Queue - documentation for POE's priority queue interface

SYNOPSIS

  $queue = POE::Queue::Foo->new();

  $payload_id = $queue->enqueue($priority, $payload);

  ($priority, $id, $payload) = $queue->dequeue_next();

  $next_priority = $queue->get_next_priority();
  $item_count = $queue->get_item_count();

  ($priority, $id, $payload) = $q->remove_item($id, \&filter);

  @items = $q->remove_items(\&filter, $count);  # $count is optional

  @items = $q->peek_items(\&filter, $count);  # $count is optional

  $new_priority = $q->adjust_priority($id, \&filter, $delta);
  $new_priority = $q->set_priority($id, \&filter, $priority);

DESCRIPTION

Priority queues are basically lists of arbitrary things that allow items to be inserted arbitrarily but that return them in a particular order. The order they are returned in is determined by each item's priority.

Priorities may represent anything, as long as they are numbers and represent an order from smallest to largest. Items with the same priority are entered into a queue in FIFO order. That is, items at the same priority are dequeued in the order they achieved a that priority.

POE uses priority queues to store and sequence its events. Queue items are events, and their priorities are the UNIX epoch times they are due.

$queue = POE::Queue::Foo->new();

Creates a priority queue, returning its reference.

$payload_id = $queue->enqueue($priority, $payload);

Enqueue a payload, which can be just about anything, at a specified priority level. Returns a unique ID which can be used to manipulate the payload or its priority directly.

The payload will be placed into the queue in priority order, from lowest to highest. The new payload will follow any others that already exist in the queue at the specified priority.

($priority, $id, $payload) = $queue->dequeue_next();

Returns the priority, ID, and payload of the item with the lowest priority. If several items exist with the same priority, it returns the one that was at that priority the longest.

$next_priority = $queue->get_next_priority();

Returns the priority of the item at the head of the queue. This is the lowest priority in the queue.

$item_count = $queue->get_item_count();

Returns the number of items in the queue.

($priority, $id, $payload) = $q->remove_item($id, \&filter);

Removes an item by its ID, but only if its payload passes the tests in a filter function. If a payload is found with the given ID, it is passed by reference to the filter function. This filter only allows wombats to be removed from a queue.

  sub filter {
    my $payload = $_[0];
    return 1 if $payload eq "wombat";
    return 0;
  }

Returns undef on failure, and sets $! to the reason why the call failed: ESRCH if the $id did not exist in the queue, or EPERM if the filter function returned 0.

@items = $q->remove_items(\&filter);

@items = $q->remove_items(\&filter, $count);

Removes multiple items that match a filter function from a queue. Returns them as a list of list references. Each returned item is

  [ $priority, $id, $payload ].

This filter does not allow anything to be removed.

  sub filter { 0 }

The $count is optional. If supplied, remove_items() will remove at most $count items. This is useful when you know how many items exist in the queue to begin with, as POE sometimes does. If a $count is supplied, it should be correct. There is no telling which items are removed by remove_items() if $count is too low.

@items = $q->peek_items(\&filter);

@items = $q->peek_items(\&filter, $count);

Returns a list of items that match a filter function from a queue. The items are not removed from the list. Each returned item is a list reference

  [ $priority, $id, $payload ]

This filter only lets you move monkeys.

  sub filter {
    return $_[0]->[TYPE] & IS_A_MONKEY;
  }

The $count is optional. If supplied, peek_items() will return at most $count items. This is useful when you know how many items exist in the queue to begin with, as POE sometimes does. If a $count is supplied, it should be correct. There is no telling which items are returned by peek_items() if $count is too low.

$new_priority = $q->adjust_priority($id, \&filter, $delta);

Changes the priority of an item by $delta (which can be negative). The item is identified by its $id, but the change will only happen if the supplied filter function returns true. Returns $new_priority, which is the priority of the item after it has been adjusted.

This filter function allows anything to be removed.

  sub filter { 1 }

$new_priority = $q->set_priority($id, \&filter, $priority);

Changes the priority of an item to $priority. The item is identified by its $id, but the change will only happen if the supplied filter function returns true when applied to the event payload. Returns $new_priority, which should match $priority.

BUGS

None known.

AUTHORS & COPYRIGHTS