{
    "mode": "perldoc",
    "parameter": "POE::Wheel",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/POE%3A%3AWheel/json",
    "generated": "2026-06-11T13:12:03Z",
    "synopsis": "This base class has no synopsis. Please consult one of the subclasses instead.",
    "sections": {
        "NAME": {
            "content": "POE::Wheel - event-driven mixins for POE::Session\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "This base class has no synopsis. Please consult one of the subclasses instead.\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "A POE::Wheel object encapsulates a bundle of event handlers that perform a specific task. It\nalso manages the event watchers that trigger those handlers.\n\nObject lifetime is very important for POE wheels. At creation time, most wheels will add\nanonymous event handlers to the currently active session. In other words, the session that\ncreated the wheel is modified to handle new events. Event watchers may also be initialized as\nnecessary to trigger the new handlers. These event watchers are also owned by the session that\ncreated the wheel.\n\nSessions must not expose their wheels to other sessions. Doing so will likely cause problems\nbecause wheels are tightly integrated with the sessions that created them. For example, calling",
            "subsections": [
                {
                    "name": "put",
                    "content": "watcher is already defined in the wheel's owner. Calling put() outside that session will enable\nthe write-okay watcher in the wrong session, and the event will never be handled.\n\nLikewise, wheels must be destroyed from within their creator sessions. Otherwise breakage will\noccur when the wheels' DESTROY methods try to unregister event handlers and watchers from the\nwrong sessions. To simplify things, it's recommended to store POE::Wheel instances in heaps of\nthe sessions that created them.\n\nFor example, creating a POE::Wheel::FollowTail object will register an event handler that\nperiodically polls a file for new information. It will also start the timer that triggers the\nperiodic polling.\n\nuse POE;\nuse POE::Wheel::FollowTail;\n\nmy @filestotail = qw( messages maillog security );\n\nforeach my $filename (@filestotail) {\nPOE::Session->create(\ninlinestates => {\nstart => sub {\npush @{$[HEAP]{messages}}, POE::Wheel::FollowTail->new(\nFilename   => \"/var/log/$filename\",\nInputEvent => \"gotinput\",\n);\n},\ngotinput => sub {\nprint \"$filename: $[ARG0]\\n\";\n},\n}\n);\n}\n\nPOE::Kernel->run();\nexit;\n\nAs illustrated in the previous example it is possible---sometimes recommended---to create more\nthan one POE::Wheel of a particular type in the same session. A session with multiple wheels may\nscale better than separate sessions with one wheel apiece. When in doubt, benchmark.\n\nUnlike components (or cheese), wheels do not stand alone. Each wheel must be created by a\nsession in order to register event watchers and handlers within that session. Wheels are thusly\ntightly coupled to their creator sessions and cannot be passed to other sessions.\n\nFILTERS, AND DRIVERS\nMany wheels perform data transfer operations on filehandles (which, as you probably know,\nincludes sockets, pipes, and just about anything else that can store or transfer data).\n\nTo avoid subclass hell, POE::Wheel objects may be customized at creation time by including other\nobjects from the POE::Filter and POE::Driver namespaces.\n"
                },
                {
                    "name": "Filters",
                    "content": "POE \"filters\" implement data parsers and serializers. For example, POE::Filter::Line parses\nstreams into records separated by some string (the traditional network newline by default). The\nLine filter also adds record separators to data being output.\n\nPOE::Filter::HTTPD is a more complex example. It implements a subset of the server-side of the\nHTTP protocol. Input streams are parsed into HTTP requests and wrapped in HTTP::Request objects.\nServer code sends HTTP::Response objects back to the client, which are serialized so they may be\nsent to a socket.\n\nMost wheels use POE::Filter::Line by default.\n"
                },
                {
                    "name": "Drivers",
                    "content": "POE \"drivers\" implement strategies for sending data to a filehandle and receiving input from it.\nA single POE::Wheel class may interact with files, pipes, sockets, or devices by using the\nappropriate driver.\n\nPOE::Driver::SysRW is the only driver that comes with POE. sysread() and syswrite() can handle\nnearly every kind of stream interaction, so there hasn't been much call for another type of\ndriver.\n"
                }
            ]
        },
        "METHODS": {
            "content": "POE::Wheel defines a common interface that most subclasses use. Subclasses may implement other\nmethods, especially to help perform their unique tasks. If something useful isn't documented\nhere, see the subclass before implementing a feature.\n",
            "subsections": [
                {
                    "name": "Required Methods",
                    "content": "These methods are required by all subclasses.\n\nnew LOTSOFSTUFF"
                },
                {
                    "name": "new",
                    "content": "continue to function for as long as it exists, although other methods may alter the way it\nfunctions.\n\nPart of any wheel's construction is the registration of anonymous event handlers to perform\nwheel-specific tasks. Event watchers are also started to trigger the handlers when relevant\nactivity occurs.\n\nEvery wheel has a different purpose and requires different constructor parameters, so\nLOTSOFSTUFF is documented in each particular subclass.\n\nDESTROY\nDESTROY is Ye Olde Perl Object Destructor. When the wheel's last strong reference is\nrelinquished, DESTROY triggers the wheel's cleanup. The object removes itself from the session\nthat created it: Active event watchers are stopped, and anonymous event handlers are\nunregistered.\n\nevent EVENTTYPE, EVENTNAME [, EVENTTYPE, EVENTNAME, ....]"
                },
                {
                    "name": "event",
                    "content": "EVENTTYPEs and the EVENTNAMEs to emit when each type of event occurs. If an EVENTNAME is\nundefined, then the wheel will stop emitting that type of event. Or the wheel may throw an error\nif the event type is required.\n\nEVENTTYPEs differ for each wheel and correspond to the constructor parameters that match\n/.*Event$/. For example, POE::Wheel::ReadWrite may emit up to five different kinds of event:\nInputEvent, ErrorEvent, FlushedEvent, HighEvent, LowEvent. The name of each emitted event may be\nchanged at run time.\n\nThis example changes the events to emit on new input and when output is flushed. It stops the\nwheel from emitting events when errors occur.\n\n$wheel->event(\nInputEvent   => 'newinputevent',\nErrorEvent   => undef,\nFlushedEvent => 'newflushedevent',\n);\n\nI/O Methods\nWheels that perform input and output may implement some or all of these methods. The put()\nmethod is a common omission. Wheels that don't perform output do not have put() methods.\n\nput RECORD [, RECORD [, ....]]"
                },
                {
                    "name": "put",
                    "content": "wheel's associated POE::Filter so that it will be ready to transmit. The serialized stream may\nbe transmitted immediately by the wheel's POE::Driver object, or it may be buffered in the\nPOE::Driver until it can be flushed to the output filehandle.\n\nMost wheels use POE::Filter::Line and POE::Driver::SysRW by default, so it's not necessary to\nspecify them in most cases.\n"
                },
                {
                    "name": "Class Static Functions",
                    "content": "These functions expose information that is common to all wheels. They are not methods, so they\nshould not be called as methods.\n\nmy $newwheelid = POE::Wheel::allocatewheelid();\nPOE::Wheel::freewheelid($newwheelid);\n\nallocatewheelid\nThis is not a class method.\n\nEvery wheel has a unique ID. allocatewheelid() returns the next available unique wheel ID.\nWheel constructors use it to set their IDs internally.\n\npackage POE::Wheel::Example;\nuse base qw(POE::Wheel);\n\nsub new {\n# ... among other things ...\n$self->[MYWHEELID] = POE::Wheel::allocatewheelid();\nreturn $self;\n}\n\nWheel IDs are used to tell apart events from similarly typed wheels. For example, a multi-file\ntail utility may handle all file input with the same function. Wheel IDs may be used to tell\nwhich wheel generated the InputEvent being handled.\n\nWheel IDs are often used to store wheel-local state in a session's heap.\n\nsub handleerror {\nmy $wheelid = $[ARG3];\nprint \"Wheel $wheelid caught an error.  Shutting it down.\\n\";\ndelete $[HEAP]{wheels}{$wheelid};\n}\n\nIt is vital for wheels to free their allocated IDs when they are destroyed. POE::Wheel class\nkeeps track of allocated wheel IDs to avoid collisions, and they will remain in memory until\nfreed. See freewheelid().\n\nfreewheelid WHEELID\nThis is not a class method.\n"
                },
                {
                    "name": "free_wheel_id",
                    "content": "later. This is often called from a wheel's destructor.\n\npackage POE::Wheel::Example;\nuse base qw(POE::Wheel);\n\nsub DESTROY {\nmy $self = shift;\n# ... among other things ...\nPOE::Wheel::freewheelid($self->[MYWHEELID]);\n}\n\nWheel IDs may be reused, although it has never been reported. Two active wheels will never share\nthe same ID, however.\n\nID\nThis is usually implemented in the subclass!\n\nThe ID() method returns a wheel's unique ID. It is commonly used to match events with the wheels\nwhich generated them.\n\nAgain, this method is not implemented in this class! If it's missing from the subclass, please\ngo pester that module author---thanks!\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "The SEE ALSO section in POE contains a table of contents covering the entire POE distribution.\n\nPOE::Driver - A base class for file access drivers that POE::Wheel may use.\n\nPOE::Filter - A base class for data parsers and marshalers that POE::Wheel may use.\n\nPOE::Wheel::Curses - Non-blocking input for Curses.\n\nPOE::Wheel::FollowTail - Non-blocking file and FIFO monitoring.\n\nPOE::Wheel::ListenAccept - Non-blocking server for existing sockets.\n\nPOE::Wheel::ReadLine - Non-blocking console input, with full readline support.\n\nPOE::Wheel::ReadWrite - Non-blocking stream I/O.\n\nPOE::Wheel::Run - Non-blocking process creation and management.\n\nPOE::Wheel::SocketFactory - Non-blocking socket creation, supporting most protocols and modes.\n",
            "subsections": []
        },
        "BUGS": {
            "content": "It would be nice if wheels were more like proper Unix streams.\n\nAUTHORS & COPYRIGHTS\nPlease see POE for more information about authors, contributors, and POE;s licensing.\n",
            "subsections": []
        }
    },
    "summary": "POE::Wheel - event-driven mixins for POE::Session",
    "flags": [],
    "examples": [],
    "see_also": []
}