{
    "mode": "perldoc",
    "parameter": "POE::Loop",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/POE%3A%3ALoop/json",
    "generated": "2026-06-09T17:06:37Z",
    "synopsis": "$kernel->loopinitialize();\n$kernel->loopfinalize();\n$kernel->loopdotimeslice();\n$kernel->looprun();\n$kernel->loophalt();\n$kernel->loopwatchsignal($signalname);\n$kernel->loopignoresignal($signalname);\n$kernel->loopattachuidestroy($guiwindow);\n$kernel->loopresumetimewatcher($nexttime);\n$kernel->loopresettimewatcher($nexttime);\n$kernel->looppausetimewatcher();\n$kernel->loopwatchfilehandle($handle, $mode);\n$kernel->loopignorefilehandle($handle, $mode);\n$kernel->looppausefilehandle($handle, $mode);\n$kernel->loopresumefilehandle($handle, $mode);",
    "sections": {
        "NAME": {
            "content": "POE::Loop - documentation for POE's event loop bridge interface\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "$kernel->loopinitialize();\n$kernel->loopfinalize();\n$kernel->loopdotimeslice();\n$kernel->looprun();\n$kernel->loophalt();\n\n$kernel->loopwatchsignal($signalname);\n$kernel->loopignoresignal($signalname);\n$kernel->loopattachuidestroy($guiwindow);\n\n$kernel->loopresumetimewatcher($nexttime);\n$kernel->loopresettimewatcher($nexttime);\n$kernel->looppausetimewatcher();\n\n$kernel->loopwatchfilehandle($handle, $mode);\n$kernel->loopignorefilehandle($handle, $mode);\n$kernel->looppausefilehandle($handle, $mode);\n$kernel->loopresumefilehandle($handle, $mode);\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "POE::Loop is a virtual base class that defines a standard event loop interface. POE::Loop\nsubclasses mix into POE::Kernel and implement the features needed to manage underlying event\nloops in a consistent fashion. This documentation covers the interface, which is shared by all\nsubclasses.\n\nAs POE::Kernel loads, it searches through %INC for event loop modules. POE::Kernel loads the\nmost appropriate POE::Loop subclass for the event loop it finds. The subclass slots its methods\ninto POE::Kernel, completing the class at load time. POE and POE::Kernel provide ways to state\nthe desired event loop in case the auto-detection makes a mistake or the developer prefers to be\nexplicit. See \"Using POE with Other Event Loops\" in POE::Kernel for instructions on how to\nactually use POE with other event loops, event loop naming conventions, and other details.\n\nPOE::Loop subclasses exist for many of the event loops Perl supports: select(), IO::Poll,\nWxWindows, EV, Glib, Event, and so on. See CPAN for a full list.\n",
            "subsections": []
        },
        "GENERAL NOTES": {
            "content": "As previously noted, POE::Loop subclasses provide additional methods to POE::Kernel and are not\nproper objects in themselves.\n\nEach POE::Loop subclass first defines its own namespace and version within it. This way CPAN and\nother things can track its version. They then switch to the POE::Kernel package to define their\nadditional methods.\n\nPOE::Loop is designed as a mix-in class because Perl imposed a performance penalty for method\ninheritance at the time the class was designed. This could be changed in the future, but it will\nrequire cascaded changes in several other classes.\n\nHere is a skeleton of a POE::Loop subclass:\n\nuse strict;\n\n# YourToolkit bridge for POE::Kernel;\n\npackage POE::Loop::YourToolkit;\n\nuse vars qw($VERSION);\n$VERSION = '1.000'; # NOTE - Should be #.### (three decimal places)\n\npackage POE::Kernel;\n\n# Define private lexical data here.\n# Implement the POE::Loop interface here.\n\n1;\n\nEND\n\n=head1 NAME\n\n... documentation goes here ...\n\n=cut\n",
            "subsections": []
        },
        "PUBLIC INTERFACE": {
            "content": "POE::Loop's public interface is divided into four parts: administrative methods, signal handler\nmethods, time management methods, and filehandle watcher methods. Each group and its members\nwill be described in detail shortly.\n\nPOE::Loop subclasses use lexical variables to keep track of things. Exact implementation is left\nup to the subclass' author. POE::Loop::Select keeps its bit vectors for select() calls in\nclass-scoped (static) lexical variables. POE::Loop::Gtk tracks a single time watcher and\nmultiple file watchers there.\n\nBridges often employ private methods as callbacks from their event loops. The Event, Gtk, and Tk\nbridges do this. Private callback names should begin with \"loop\" to avoid colliding with other\nmethods.\n\nDevelopers should look at existing bridges to get a feel for things. The \"-m\" flag for perldoc\nwill show a module in its entirety.\n\nperldoc -m POE::Loop::Select\nperldoc -m POE::Loop::Gtk\n...\n",
            "subsections": [
                {
                    "name": "Administrative Methods",
                    "content": "These methods initialize and finalize an event loop, run the loop to process events, and halt\nit.\n\nloopinitialize\nInitialize the event loop. Graphical toolkits especially need some sort of init() call or\nsequence to set up. For example, Tk requires a widget to be created before any events will be\nprocessed, and the program's user interface will be considered destroyed if that widget is\nclosed.\n\nsub loopinitialize {\nmy $self = shift;\n\n$poemainwindow = Tk::MainWindow->new();\ndie \"could not create a main Tk window\" unless defined $poemainwindow;\n$self->signaluidestroy($poemainwindow);\n}\n\nPOE::Loop::Select initializes its select() bit vectors.\n\nsub loopinitialize {\n@loopvectors = ( '', '', '' );\nvec($loopvectors[MODERD], 0, 1) = 0;\nvec($loopvectors[MODEWR], 0, 1) = 0;\nvec($loopvectors[MODEEX], 0, 1) = 0;\n}\n\nloopfinalize\nFinalize the event loop. Most event loops do not require anything here since they have already\nstopped by the time loopfinalize() is called. However, this is a good place to check that a\nbridge has not leaked memory or data. This example comes from POE::Loop::Event.\n\nsub loopfinalize {\nmy $self = shift;\n\nforeach my $fd (0..$#filenowatcher) {\nnext unless defined $filenowatcher[$fd];\nforeach my $mode (MODERD, MODEWR, MODEEX) {\nPOE::Kernel::warn(\n\"Mode $mode watcher for fileno $fd is defined during loop finalize\"\n) if defined $filenowatcher[$fd]->[$mode];\n}\n}\n\n$self->loopignoreallsignals();\n}\n\nloopdotimeslice\nWait for time to pass or new events to occur, and dispatch any events that become due. If the\nunderlying event loop does this through callbacks, then loopdotimeslice() will either provide\nminimal glue or do nothing.\n\nFor example, loopdotimeslice() for POE::Loop::Select sets up and calls select(). If any files\nor other resources become active, it enqueues events for them. Finally, it triggers dispatch for\nany events are due.\n\nOn the other hand, the Gtk event loop handles all this, so loopdotimeslice() is empty for the\nGtk bridge.\n\nA sample loopdotimeslice() implementation is not presented here because it would either be\nquite large or empty. See each POE::Loop::IOPoll or Select for large ones. Event and Gtk are\nempty.\n\nThe bridges for Poll and Select for large ones. The ones for Event and Gtk are empty, and Tk's\n(in POE::Loop::TkCommon) is rather small.\n\nlooprun\nRun an event loop until POE has no more sessions to handle events. This method tends to be quite\nsmall, and it is often implemented in terms of loopdotimeslice(). For example,\nPOE::Loop::IOPoll implements it:\n\nsub looprun {\nmy $self = shift;\nwhile ($self->datasescount()) {\n$self->loopdotimeslice();\n}\n}\n\nThis method is even more trivial when an event loop handles it. This is from the Gtk bridge:\n\nsub looprun {\nunless (defined $watchertimer) {\n$watchertimer = Gtk->idleadd(\\&loopresumetimer);\n}\nGtk->main;\n}\n\nloophalt"
                },
                {
                    "name": "loop_halt",
                    "content": "trivial for external event loops or empty for ones that are implemented in the bridge itself\n(IOPoll, Select).\n\nFor example, the looprun() method in the Poll bridge exits when sessions have run out, so its"
                },
                {
                    "name": "loop_halt",
                    "content": "sub loophalt {\n# does nothing\n}\n\nGtk, however, needs to be stopped because it does not know when POE is done.\n\nsub loophalt {\nGtk->mainquit();\n}\n"
                },
                {
                    "name": "Signal Management Methods",
                    "content": "These methods enable and disable signal watchers. They are used by POE::Resource::Signals to\nmanage an event loop's signal watchers.\n\nMost event loops use Perl's %SIG to watch for signals. This is so common that\nPOE::Loop::PerlSignals implements the interface on behalf of other subclasses.\n\nloopwatchsignal SIGNALNAME\nWatch for a given SIGNALNAME. SIGNALNAME is the version found in %SIG, which tends to be the\noperating signal's name with the leading \"SIG\" removed.\n\nPOE::Loop::PerlSignals' implementation adds callbacks to %SIG except for CHLD/CLD, which begins\na waitpid() polling loop instead.\n\nAs of this writing, all of the POE::Loop subclasses register their signal handlers through\nPOE::Loop::PerlSignals.\n\nThere are three types of signal handlers:\n\nCHLD/CLD handlers, when managed by the bridges themselves, poll for exited children. POE::Kernel\ndoes most of this, but loopwatchsignal() still needs to start the process.\n\nPIPE handlers. The PIPE signal event must be sent to the session that is active when the signal\noccurred.\n\nEverything else. Signal events for everything else are sent to POE::Kernel, where they are\ndistributed to every session.\n\nThe loopwatchsignal() methods tends to be very long, so an example is not presented here. The\nEvent and Select bridges have good examples, though.\n\nloopignoresignal SIGNALNAME\nStop watching SIGNALNAME. POE::Loop::PerlSignals does this by resetting the %SIG for the\nSIGNALNAME to a sane value.\n\n$SIG{CHLD} is left alone so as to avoid interfering with system() and other things.\n\nSIGPIPE is generally harmless since POE generates events for this condition. Therefore\n$SIG{PIPE} is set to \"IGNORE\" when it's not being handled.\n\nAll other signal handlers default to \"DEFAULT\" when not in use.\n\nloopattachuidestroy WIDGET\nPOE, when used with a graphical toolkit, should shut down when the user interface is closed."
                },
                {
                    "name": "loop_attach_uidestroy",
                    "content": "The shutdown is done by firing a UIDESTROY signal when the WIDGET's closure or destruction\ncallback is invoked. UIDESTROY guarantees the program will shut down by virtue of being terminal\nand non-maskable.\n"
                },
                {
                    "name": "loop_attach_uidestroy",
                    "content": "interfaces. All other subclasses leave the method empty.\n\nHere's Gtk's:\n\nsub loopattachuidestroy {\nmy ($self, $window) = @;\n$window->signalconnect(\ndeleteevent => sub {\nif ($self->datasescount()) {\n$self->dispatchevent(\n$self, $self,\nENSIGNAL, ETSIGNAL, [ 'UIDESTROY' ],\nFILE, LINE, undef, monotime(), -LINE\n);\n}\nreturn 0;\n}\n);\n}\n"
                },
                {
                    "name": "Alarm and Time Management Methods",
                    "content": "These methods enable and disable a time watcher or alarm in the underlying event loop. POE only\nrequires one, which is reused or re-created as necessary.\n\nMost event loops trigger callbacks when time has passed. It is the bridge's responsibility to\nregister and unregister a callback as needed. When invoked, the callback should dispatch events\nthat have become due and possibly set up a new callback for the next event to be dispatched.\n\nThe time management methods may accept NEXTEVENTTIME. This is the time the next event will\nbecome due, in UNIX epoch time. NEXTEVENTTIME is a real number and may have sub-second\naccuracy. It is the bridge's responsibility to convert this value into something the underlying\nevent loop requires.\n\nloopresumetimewatcher NEXTEVENTTIME\nResume an already active time watcher. It is used with looppausetimewatcher() to provide less\nexpensive timer toggling for frequent use cases. As mentioned above, NEXTEVENTTIME is in UNIX\nepoch time and may have sub-second accuracy.\n"
                },
                {
                    "name": "loop_resume_time_watcher",
                    "content": "loop. For example, POE::Loop::Gtk implements it this way:\n\nsub loopresumetimewatcher {\nmy ($self, $nexttime) = @;\n$nexttime -= time();\n$nexttime *= 1000;\n$nexttime = 0 if $nexttime < 0;\n$watchertimer = Gtk->timeoutadd(\n$nexttime, \\&loopeventcallback\n);\n}\n\nThis method is usually empty in bridges that implement their own event loops.\n\nloopresettimewatcher NEXTEVENTTIME\nReset a time watcher, often by stopping or destroying an existing one and creating a new one in\nits place. It is often a wrapper for loopresumetimewatcher() that first destroys an existing\nwatcher. For example, POE::Loop::Gkt's implementation:\n\nsub loopresettimewatcher {\nmy ($self, $nexttime) = @;\nGtk->timeoutremove($watchertimer);\nundef $watchertimer;\n$self->loopresumetimewatcher($nexttime);\n}\n\nlooppausetimewatcher\nPause a time watcher without destroying it, if the underlying event loop supports such a thing.\nPOE::Loop::Event does support it:\n\nsub looppausetimewatcher {\n$watchertimer or return;\n$watchertimer->stop();\n}\n"
                },
                {
                    "name": "File Activity Management Methods",
                    "content": "These methods enable and disable file activity watchers. There are four methods:"
                },
                {
                    "name": "loop_watch_filehandle",
                    "content": ""
                },
                {
                    "name": "loop_resume_filehandle",
                    "content": "and \"watch\", respectively.\n\nAll the methods take the same two parameters: a file HANDLE and a file access MODE. Modes may be\nMODERD, MODEWR, or MODEEX. These constants are defined by POE::Kernel and correspond to the\nsemantics of POE::Kernel's selectread(), selectwrite(), and selectexpedite() methods.\n\nPOE calls MODEEX \"expedited\" because it often signals that a file is ready for out-of-band\ninformation. Not all event loops handle MODEEX. For example, Tk:\n\nsub loopwatchfilehandle {\nmy ($self, $handle, $mode) = @;\nmy $fileno = fileno($handle);\n\nmy $tkmode;\nif ($mode == MODERD) {\n$tkmode = 'readable';\n}\nelsif ($mode == MODEWR) {\n$tkmode = 'writable';\n}\nelse {\n# The Tk documentation implies by omission that expedited\n# filehandles aren't, uh, handled.  This is part 1 of 2.\nconfess \"Tk does not support expedited filehandles\";\n}\n\n# ... rest omitted ....\n}\n\nloopwatchfilehandle FILEHANDLE, IOMODE\nWatch a FILEHANDLE for activity in a given IOMODE. Depending on the underlying event loop, a\nwatcher or callback will be registered for the FILEHANDLE. Activity in the specified IOMODE\n(read, write, or out of band) will trigger emission of the proper event in application space.\n\nPOE::Loop::Select sets the fileno()'s bit in the proper select() bit vector. It also keeps track\nof which file descriptors are active.\n\nsub loopwatchfilehandle {\nmy ($self, $handle, $mode) = @;\nmy $fileno = fileno($handle);\nvec($loopvectors[$mode], $fileno, 1) = 1;\n$loopfilenos{$fileno} |= (1<<$mode);\n}\n\nloopignorefilehandle FILEHANDLE, IOMODE\nStop watching the FILEHANDLE in a given IOMODE. Stops (and possibly destroys) an event watcher\ncorresponding to the FILEHANDLE and IOMODE.\n\nPOE::Loop::IOPoll's loopignorefilehandle() manages descriptor/mode bits for its poll()\nmethod here. It also performs some cleanup if a descriptor is no longer being watched after this\nignore call.\n\nsub loopignorefilehandle {\nmy ($self, $handle, $mode) = @;\nmy $fileno = fileno($handle);\n\nmy $type = modetopoll($mode);\nmy $current = $pollfdmasks{$fileno} || 0;\nmy $new = $current & ~$type;\n\nif (TRACEFILES) {\nPOE::Kernel::warn(\nsprintf(\n\"<fh> Ignore $fileno: \" .\n\": Current mask: 0x%02X - removing 0x%02X = 0x%02X\\n\",\n$current, $type, $new\n)\n);\n}\n\nif ($new) {\n$pollfdmasks{$fileno} = $new;\n}\nelse {\ndelete $pollfdmasks{$fileno};\n}\n}\n\nlooppausefilehandle FILEHANDLE, IOMODE\nThis is a lightweight form of loopignorefilehandle(). It is used along with"
                },
                {
                    "name": "loop_resume_filehandle",
                    "content": "particular IOMODE.\n\nSome event loops, such as Event.pm, support their file watchers being disabled and re-enabled\nwithout the need to destroy and re-create the watcher objects.\n\nsub looppausefilehandle {\nmy ($self, $handle, $mode) = @;\nmy $fileno = fileno($handle);\n$filenowatcher[$fileno]->[$mode]->stop();\n}\n\nBy comparison, Event's loopignorefilehandle() method cancels and destroys the watcher object.\n\nsub loopignorefilehandle {\nmy ($self, $handle, $mode) = @;\nmy $fileno = fileno($handle);\nif (defined $filenowatcher[$fileno]->[$mode]) {\n$filenowatcher[$fileno]->[$mode]->cancel();\nundef $filenowatcher[$fileno]->[$mode];\n}\n}\n\nIgnoring and re-creating watchers is relatively expensive, so POE::Kernel's selectpauseread()\nand selectresumeread() methods (and the corresponding ones for write and expedite) use the\nfaster versions.\n\nloopresumefilehandle FILEHANDLE, IOMODE\nThis is a lightweight form of loopwatchfilehandle(). It is used along with"
                },
                {
                    "name": "loop_pause_filehandle",
                    "content": "particular IOMODE.\n"
                }
            ]
        },
        "HOW POE FINDS EVENT LOOP BRIDGES": {
            "content": "This is a rehash of \"Using POE with Other Event Loops\" in POE::Kernel.\n\nFirstly, if a POE::Loop subclass is manually loaded before POE::Kernel, then that will be used.\nEnd of story.\n\nIf one isn't, POE::Kernel searches for an external event loop module in %INC. For each module in\n%INC, corresponding POE::XS::Loop and POE::Loop subclasses are tried.\n\nFor example, if IO::Poll is loaded, POE::Kernel tries\n\nuse POE::XS::Loop::IOPoll;\nuse POE::Loop::IOPoll;\n\nThis is relatively expensive, but it ensures that POE::Kernel can find new POE::Loop subclasses\nwithout defining them in a central registry.\n\nPOE::Loop::Select is the fallback event loop. It's loaded if no other event loop can be found in\n%INC.\n\nIt can't be repeated often enough that event loops must be loaded before POE::Kernel. Otherwise\nthey will not be present in %INC, and POE::Kernel will not detect them.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "POE, POE::Loop::Event, POE::Loop::Gtk, POE::Loop::IOPoll, POE::Loop::Select, POE::Loop::Tk.\n\nPOE::Test::Loops is POE's event loop tests released as a separate, reusable distribution.\nPOE::Loop authors are encouraged to use the tests for their own distributions.\n",
            "subsections": []
        },
        "BUGS": {
            "content": "None known.\n\nAUTHORS & LICENSING\nPlease see POE for more information about authors, contributors, and POE's licensing.\n",
            "subsections": []
        }
    },
    "summary": "POE::Loop - documentation for POE's event loop bridge interface",
    "flags": [],
    "examples": [],
    "see_also": []
}