1POE::Queue(3) User Contributed Perl Documentation POE::Queue(3)
2
6 POE::Queue - documentation for POE's priority queue interface
7
9 $queue = POE::Queue::Foo->new();
10 $payload_id = $queue->enqueue($priority, $payload);
12 ($priority, $id, $payload) = $queue->dequeue_next();
14 $next_priority = $queue->get_next_priority();
16 $item_count = $queue->get_item_count();
17 ($priority, $id, $payload) = $q->remove_item($id, \&filter);
19 @items = $q->remove_items(\&filter, $count); # $count is optional
21 @items = $q->peek_items(\&filter, $count); # $count is optional
23 $new_priority = $q->adjust_priority($id, \&filter, $delta);
25 $new_priority = $q->set_priority($id, \&filter, $priority);
26
28 Priority queues are basically lists of arbitrary things that allow
29 items to be inserted arbitrarily but that return them in a particular
30 order. The order they are returned in is determined by each item's
31 priority.
32 Priorities may represent anything, as long as they are numbers and rep‐
34 resent an order from smallest to largest. Items with the same priority
35 are entered into a queue in FIFO order. That is, items at the same
36 priority are dequeued in the order they achieved a that priority.
37 POE uses priority queues to store and sequence its events. Queue items
39 are events, and their priorities are the UNIX epoch times they are due.
40 $queue = POE::Queue::Foo->new();
42 Creates a priority queue, returning its reference.
43 $payload_id = $queue->enqueue($priority, $payload);
45 Enqueue a payload, which can be just about anything, at a specified
46 priority level. Returns a unique ID which can be used to manipu‐
47 late the payload or its priority directly.
48 The payload will be placed into the queue in priority order, from
50 lowest to highest. The new payload will follow any others that
51 already exist in the queue at the specified priority.
52 ($priority, $id, $payload) = $queue->dequeue_next();
54 Returns the priority, ID, and payload of the item with the lowest
55 priority. If several items exist with the same priority, it
56 returns the one that was at that priority the longest.
57 $next_priority = $queue->get_next_priority();
59 Returns the priority of the item at the head of the queue. This is
60 the lowest priority in the queue.
61 $item_count = $queue->get_item_count();
63 Returns the number of items in the queue.
64 ($priority, $id, $payload) = $q->remove_item($id, \&filter);
66 Removes an item by its ID, but only if its payload passes the tests
67 in a filter function. If a payload is found with the given ID, it
68 is passed by reference to the filter function. This filter only
69 allows wombats to be removed from a queue.
70 sub filter {
72 my $payload = $_[0];
73 return 1 if $payload eq "wombat";
74 return 0;
75 }
76 Returns undef on failure, and sets $! to the reason why the call
78 failed: ESRCH if the $id did not exist in the queue, or EPERM if
79 the filter function returned 0.
80 @items = $q->remove_items(\&filter);
82 @items = $q->remove_items(\&filter, $count);
83 Removes multiple items that match a filter function from a queue.
84 Returns them as a list of list references. Each returned item is
85 [ $priority, $id, $payload ].
87 This filter does not allow anything to be removed.
89 sub filter { 0 }
91 The $count is optional. If supplied, remove_items() will remove at
93 most $count items. This is useful when you know how many items
94 exist in the queue to begin with, as POE sometimes does. If a
95 $count is supplied, it should be correct. There is no telling
96 which items are removed by remove_items() if $count is too low.
97 @items = $q->peek_items(\&filter);
99 @items = $q->peek_items(\&filter, $count);
100 Returns a list of items that match a filter function from a queue.
101 The items are not removed from the list. Each returned item is a
102 list reference
103 [ $priority, $id, $payload ]
105 This filter only lets you move monkeys.
107 sub filter {
109 return $_[0]->[TYPE] & IS_A_MONKEY;
110 }
111 The $count is optional. If supplied, peek_items() will return at
113 most $count items. This is useful when you know how many items
114 exist in the queue to begin with, as POE sometimes does. If a
115 $count is supplied, it should be correct. There is no telling
116 which items are returned by peek_items() if $count is too low.
117 $new_priority = $q->adjust_priority($id, \&filter, $delta);
119 Changes the priority of an item by $delta (which can be negative).
120 The item is identified by its $id, but the change will only happen
121 if the supplied filter function returns true. Returns $new_prior‐
122 ity, which is the priority of the item after it has been adjusted.
123 This filter function allows anything to be removed.
125 sub filter { 1 }
127 $new_priority = $q->set_priority($id, \&filter, $priority);
129 Changes the priority of an item to $priority. The item is identi‐
130 fied by its $id, but the change will only happen if the supplied
131 filter function returns true when applied to the event payload.
132 Returns $new_priority, which should match $priority.
133
135 POE, POE::Queue::Array
136
138 None known.
139
141 Please see POE for more information about authors, contributors, and
142 POE's licensing.
143perl v5.8.8 2006-09-01 POE::Queue(3)