{
    "mode": "perldoc",
    "parameter": "POE::Queue",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/POE%3A%3AQueue/json",
    "generated": "2026-06-12T15:39:42Z",
    "synopsis": "POE::Queue specifies additional methods not illustrated here.\n#!perl\nuse warnings;\nuse strict;\nuse POE::Queue::Array;\nmy $pqa = POE::Queue::Array->new();\n# Enqueue a few items.\nforeach my $priority (505, 404, 303, 202, 101) {\n$pqa->enqueue($priority, \"payload $priority\");\n}\n# Dequeue until the queue is drained.\nwhile (1) {\nmy ($priority, $queueid, $payload) = $pqa->dequeuenext();\nlast unless defined $priority;\nprint(\n\"dequeued id($queueid) \",\n\"priority($priority) \",\n\"payload($payload)\\n\",\n);\n}\nSample output:\ndequeued id(5) priority(101) payload(payload 101)\ndequeued id(4) priority(202) payload(payload 202)\ndequeued id(3) priority(303) payload(payload 303)\ndequeued id(2) priority(404) payload(payload 404)\ndequeued id(1) priority(505) payload(payload 505)",
    "sections": {
        "NAME": {
            "content": "POE::Queue - a flexible, generic priority queue API\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "POE::Queue specifies additional methods not illustrated here.\n\n#!perl\n\nuse warnings;\nuse strict;\nuse POE::Queue::Array;\n\nmy $pqa = POE::Queue::Array->new();\n\n# Enqueue a few items.\n\nforeach my $priority (505, 404, 303, 202, 101) {\n$pqa->enqueue($priority, \"payload $priority\");\n}\n\n# Dequeue until the queue is drained.\n\nwhile (1) {\nmy ($priority, $queueid, $payload) = $pqa->dequeuenext();\nlast unless defined $priority;\n\nprint(\n\"dequeued id($queueid) \",\n\"priority($priority) \",\n\"payload($payload)\\n\",\n);\n}\n\nSample output:\n\ndequeued id(5) priority(101) payload(payload 101)\ndequeued id(4) priority(202) payload(payload 202)\ndequeued id(3) priority(303) payload(payload 303)\ndequeued id(2) priority(404) payload(payload 404)\ndequeued id(1) priority(505) payload(payload 505)\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Priority queues may be implemented a number of ways, but they tend to behave similar to lists\nthat are kept in order by some kind of \"priority\". Enqueued items are stored such that the\n\"next\" item to be retrieved is the one with the highest priority. Subsequent fetches return the\nnext lowest priority, and so on, until the queue is emptied.\n\nPriority queues (also known as priority heaps) attempt to do this while consuming the fewest\nresources. Go read about it! It's fascinating stuff!\n\nPOE::Queue Items\nPOE::Queue items consist of three fields: A priority, a unique ID assigned at enqueue time, and\na payload. The priority and payload are specified by the caller, and the unique ID is generated\nby POE::Queue when an item is enqueued.\n\nPOE::Queue imposes two limitations on priorities: Priorities must be numeric, and lower numbers\nindicate higher priorities. Aside from that, POE::Queue doesn't care what the numbers mean.\n\nUnique IDs are handles into the queue. POE::Queue generates and returns them as new items are\nenqueued. Some methods manipulate items, and they take IDs to identify the items to alter.\n\nItem payloads are arbitrary application data. POE::Queue does not examine or alter payloads\nitself. Any methods that need to examine payloads will accept a filter function. Filter\nfunctions examine payloads so POE::Queue need not.\n",
            "subsections": []
        },
        "Public Methods": {
            "content": "POE::Queue is an API specification. Subclasses like POE::Queue::Array provide actual\nimplementations.\n\nnew\nCreates a new priority queue. Returns a reference to the queue.\n\nmy $queue = POE::Queue::Array->new();\n\nenqueue PRIORITY, PAYLOAD\nEnqueues a PAYLOAD, which can be just about anything that will fit into a Perl scalar, at a\nparticular PRIORITY level. enqueue() returns a unique ID which can be used to manipulate the\npayload or its priority directly.\n\nFollowing the UNIX tradition, lower priority numbers indicate higher priorities. The payload\nwith the lowest priority number will be dequeued first. If two payloads have the same PRIORITY,\nthen they will be dequeued in the order in which they were enqueued.\n\nIn this example, a queue is used to manage a number of alarms. The \"next\" alarm will be the one\ndue soonest.\n\nmy $payloadid = $queue->enqueue($alarmtime, [ \"stuff\" ]);\n\ndequeuenext\nRemoves the next item from the queue, returning it as three fields: priority, ID and payload.\n\nThe \"next\" item is the one with the lowest priority number. If multiple items exist with the\nsame priority, dequeuenext() will return the one that was given the priority first.\n\nITEM: while (1) {\nmy ($priority, $id, $payload) = $queue->dequeuenext();\nlast ITEM unless defined $priority;\n...;\n}\n\ngetnextpriority\nReturns the priority of the item at the head of the queue. This is the lowest numeric priority\nin the queue.\n",
            "subsections": [
                {
                    "name": "get_next_priority",
                    "content": "items. In this case, the queue manages multiple alarms, and there's nothing to do if the next\nalarm isn't due yet.\n\nALARM: while (1) {\nmy $nextalarmtime = $queue->getnextpriority();\nlast ALARM unless defined $nextalarmtime;\n\nif ($nextalarmtime - time() > 0) {\nsleep($nextalarmtime - time());\n}\n\nmy ($priority, $id, $payload) = $queue->dequeuenext();\n...;\n}\n\ngetitemcount\nReturns the number of items in the queue. It's another way to tell whether the queue has been\nfully drained. Here's an alternative version of the example for getnextpriority().\n\nALARM: while ($queue->getitemcount()) {\nmy $nextalarmtime = $queue->getnextpriority();\nif ($nextalarmtime - time() > 0) {\nsleep($nextalarmtime - time());\n}\n\nmy ($priority, $id, $payload) = $queue->dequeuenext();\n...;\n}\n\nremoveitem ITEMID, FILTERFUNCTION\nRemoves a single item by its ID, but only if a FILTERFUNCTION approves of the item's payload.\n\nIf a payload is found with the given ITEMID, it is passed to FILTERFUNCTION for examination.\nIf FILTERFUNCTION returns true, the item is removed from the queue and is returned as three\nfields.\n\nmy ($priority, $id, $payload) = $queue->removeitem(\n$targetid, \\&monkeys\n);\n\nsub monkeys {\nmy $payload = shift;\n$payload->{type} eq \"monkey\";\n}\n\nThe returned $priority will be undef on failure, and $! will be set to the reason why the item\ncouldn't be removed. That will be ESRCH if the ITEMID was not found in the queue, or EPERM if\nthe filter function returned false.\n\nremoveitems FILTERFUNCTION [, MAXITEMCOUNT ]\nRemoves and returns items from the queue that match a FILTERFUNCTION. removeitems() will\nreturn immediately if MAXITEMCOUNT items is specified and that many items have been removed\nfrom the queue. MAXITEMCOUNT is a bit of optimization if the application knows in advance how\nmany items will match the FILTERFUNCTION.\n\nReturns a list of items that were removed. Each item is an array reference containing a\npriority, item ID, and payload. Returns nothing if FILTERFUNCTION matched nothing.\n\n# Remove up to 12 monkeys.\nmy @monkeys = $queue->removeitems(\\&monkeys, 12);\nforeach my $monkey (@monkeys) {\nmy ($priority, $id, $payload) = @$monkey;\nprint(\n\"Removed monkey:\\n\",\n\"  priority = $priority\\n\",\n\"  queue id = $id\\n\",\n\"  payload  = $payload\\n\",\n);\n}\n\nThere is no guarantee which items will be removed if MAXITEMCOUNT is specified too low.\n\npeekitems FILTERFUNCTION [, MAXITEMCOUNT ]"
                },
                {
                    "name": "peek_items",
                    "content": "removing them from the queue.\n\nmy @entirequeue = $queue->peekitems(sub { 1 });\nforeach my $item (@entirequeue) {\nmy ($priority, $id, $payload) = @$item;\nprint(\n\"Item:\\n\",\n\"  priority = $priority\\n\",\n\"  queue id = $id\\n\",\n\"  payload  = $payload\\n\",\n);\n}\n\nadjustpriority ITEMID, FILTERFUNCTION, DELTA\nChanges the priority of an item by DELTA. The item is identified by its ITEMID, and the change\nwill only happen if the item's payload satisfies a FILTERFUNCTION. Returns the new priority,\nwhich is the previous priority + DELTA. DELTA may be negative.\n\nmy $newpriority = $queue->adjustpriority(\n$itemid, \\&oneofmine, 100\n);\n\nsub oneofmine {\nmy $payload = shift;\nreturn $payload->{owner} == $me;\n}\n\nReturns undef if the item's priority could not be adjusted, and sets $! to explain why: ESRCH\nmeans that the ITEMID could not be found, and EPERM means that the FILTERFUNCTION was not\nsatisfied.\n\nsetpriority ITEMID, FILTERFUNCTION, ABSOLUTEPRIORITY\nSets an item's priority to a new ABSOLUTEPRIORITY. The item is identified by its ITEMID, and\nthe change will only be allowed to happen if the item's payload satisfies a FILTERFUNCTION.\nReturns the new priority, which should match ABSOLUTEPRIORITY.\n\nReturns undef if the item's priority could not be set, and sets $! to explain why: ESRCH means\nthat the ITEMID could not be found, and EPERM means that the FILTERFUNCTION was not satisfied.\n\nmy $newpriority = $queue->setpriority(\n$itemid, \\&oneofmine, time() + 60\n);\n\nunless (defined $newpriority) {\ndie \"one of our submarines is missing: $itemid\" if $! == ESRCH;\ndie \"setpriority disallowed for item $itemid\" if $! == EPERM;\ndie $!;\n}\n\nsub oneofmine {\n$[0]{owner} == $me;\n}\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "POE, POE::Queue::Array\n",
            "subsections": []
        },
        "BUGS": {
            "content": "None known.\n\nAUTHORS & COPYRIGHTS\nPlease see POE for more information about authors, contributors, and POE's licensing.\n",
            "subsections": []
        }
    },
    "summary": "POE::Queue - a flexible, generic priority queue API",
    "flags": [],
    "examples": [],
    "see_also": []
}