.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "POE::Wheel 3pm"
.TH POE::Wheel 3pm "2020-02-07" "perl v5.30.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
POE::Wheel \- event\-driven mixins for POE::Session
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
This base class has no synopsis.
Please consult one of the subclasses instead.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A POE::Wheel object encapsulates a bundle of event handlers that
perform a specific task.  It also manages the event watchers that
trigger those handlers.
.PP
Object lifetime is very important for \s-1POE\s0 wheels.  At creation time,
most wheels will add anonymous event handlers to the currently active
session.  In other words, the session that created the wheel is
modified to handle new events.  Event watchers may also be initialized
as necessary to trigger the new handlers.  These event watchers are
also owned by the session that created the wheel.
.PP
Sessions must not expose their wheels to other sessions.  Doing so
will likely cause problems because wheels are tightly integrated with
the sessions that created them.  For example, calling \fBput()\fR on a
POE::Wheel::ReadWrite instance may enable a write-okay watcher.  The
handler for this watcher is already defined in the wheel's owner.
Calling \fBput()\fR outside that session will enable the write-okay watcher
in the wrong session, and the event will never be handled.
.PP
Likewise, wheels must be destroyed from within their creator sessions.
Otherwise breakage will occur when the wheels' \s-1DESTROY\s0 methods try to
unregister event handlers and watchers from the wrong sessions.  To
simplify things, it's recommended to store POE::Wheel instances in
heaps of the sessions that created them.
.PP
For example, creating a POE::Wheel::FollowTail object will register an
event handler that periodically polls a file for new information.  It
will also start the timer that triggers the periodic polling.
.PP
.Vb 2
\&  use POE;
\&  use POE::Wheel::FollowTail;
\&
\&  my @files_to_tail = qw( messages maillog security );
\&
\&  foreach my $filename (@files_to_tail) {
\&    POE::Session\->create(
\&      inline_states => {
\&        _start => sub {
\&          push @{$_[HEAP]{messages}}, POE::Wheel::FollowTail\->new(
\&            Filename   => "/var/log/$filename",
\&            InputEvent => "got_input",
\&          );
\&        },
\&        got_input => sub {
\&          print "$filename: $_[ARG0]\en";
\&        },
\&      }
\&    );
\&  }
\&
\&  POE::Kernel\->run();
\&  exit;
.Ve
.PP
As illustrated in the previous example it is possible\-\-\-sometimes
recommended\-\-\-to create more than one POE::Wheel of a particular type
in the same session.  A session with multiple wheels may scale better
than separate sessions with one wheel apiece.  When in doubt,
benchmark.
.PP
Unlike components (or cheese), wheels do not stand alone.  Each wheel
must be created by a session in order to register event watchers and
handlers within that session.  Wheels are thusly tightly coupled to
their creator sessions and cannot be passed to other sessions.
.SH "FILTERS, AND DRIVERS"
.IX Header "FILTERS, AND DRIVERS"
Many wheels perform data transfer operations on filehandles (which, as
you probably know, includes sockets, pipes, and just about anything
else that can store or transfer data).
.PP
To avoid subclass hell, POE::Wheel objects may be customized at
creation time by including other objects from the POE::Filter and
POE::Driver namespaces.
.SS "Filters"
.IX Subsection "Filters"
\&\s-1POE\s0 \*(L"filters\*(R" implement data parsers and serializers.  For example,
POE::Filter::Line parses streams into records separated by some string
(the traditional network newline by default).  The Line filter also
adds record separators to data being output.
.PP
POE::Filter::HTTPD is a more complex example.  It implements a subset
of the server-side of the \s-1HTTP\s0 protocol.  Input streams are parsed
into \s-1HTTP\s0 requests and wrapped in HTTP::Request objects.  Server code
sends HTTP::Response objects back to the client, which are serialized
so they may be sent to a socket.
.PP
Most wheels use POE::Filter::Line by default.
.SS "Drivers"
.IX Subsection "Drivers"
\&\s-1POE\s0 \*(L"drivers\*(R" implement strategies for sending data to a filehandle
and receiving input from it.  A single POE::Wheel class may interact
with files, pipes, sockets, or devices by using the appropriate
driver.
.PP
POE::Driver::SysRW is the only driver that comes with \s-1POE.\s0  \fBsysread()\fR
and \fBsyswrite()\fR can handle nearly every kind of stream interaction, so
there hasn't been much call for another type of driver.
.SH "METHODS"
.IX Header "METHODS"
POE::Wheel defines a common interface that most subclasses use.
Subclasses may implement other methods, especially to help perform
their unique tasks.  If something useful isn't documented here, see
the subclass before implementing a feature.
.SS "Required Methods"
.IX Subsection "Required Methods"
These methods are required by all subclasses.
.PP
\fInew \s-1LOTS_OF_STUFF\s0\fR
.IX Subsection "new LOTS_OF_STUFF"
.PP
\&\fBnew()\fR instantiates and initializes a new wheel object and returns it.
The new wheel will continue to function for as long as it exists,
although other methods may alter the way it functions.
.PP
Part of any wheel's construction is the registration of anonymous
event handlers to perform wheel-specific tasks.  Event watchers are
also started to trigger the handlers when relevant activity occurs.
.PP
Every wheel has a different purpose and requires different constructor
parameters, so \s-1LOTS_OF_STUFF\s0 is documented in each particular
subclass.
.PP
\fI\s-1DESTROY\s0\fR
.IX Subsection "DESTROY"
.PP
\&\s-1DESTROY\s0 is Ye Olde Perl Object Destructor.  When the wheel's last
strong reference is relinquished, \s-1DESTROY\s0 triggers the wheel's
cleanup.  The object removes itself from the session that created it:
Active event watchers are stopped, and anonymous event handlers are
unregistered.
.PP
\fIevent \s-1EVENT_TYPE, EVENT_NAME\s0 [, \s-1EVENT_TYPE, EVENT_NAME, ....\s0]\fR
.IX Subsection "event EVENT_TYPE, EVENT_NAME [, EVENT_TYPE, EVENT_NAME, ....]"
.PP
\&\fBevent()\fR changes the events that a wheel will emit.  Its parameters are
one or more pairs of EVENT_TYPEs and the EVENT_NAMEs to emit when each
type of event occurs.  If an \s-1EVENT_NAME\s0 is undefined, then the wheel
will stop emitting that type of event.  Or the wheel may throw an
error if the event type is required.
.PP
EVENT_TYPEs differ for each wheel and correspond to the constructor
parameters that match /.*Event$/.  For example, POE::Wheel::ReadWrite
may emit up to five different kinds of event: InputEvent, ErrorEvent,
FlushedEvent, HighEvent, LowEvent.  The name of each emitted event may
be changed at run time.
.PP
This example changes the events to emit on new input and when output
is flushed.  It stops the wheel from emitting events when errors
occur.
.PP
.Vb 5
\&  $wheel\->event(
\&    InputEvent   => \*(Aqnew_input_event\*(Aq,
\&    ErrorEvent   => undef,
\&    FlushedEvent => \*(Aqnew_flushed_event\*(Aq,
\&  );
.Ve
.SS "I/O Methods"
.IX Subsection "I/O Methods"
Wheels that perform input and output may implement some or all of
these methods.  The \fBput()\fR method is a common omission.  Wheels that
don't perform output do not have \fBput()\fR methods.
.PP
\fIput \s-1RECORD\s0 [, \s-1RECORD\s0 [, ....]]\fR
.IX Subsection "put RECORD [, RECORD [, ....]]"
.PP
\&\fBput()\fR sends one or more RECORDs to the wheel for transmitting.  Each
\&\s-1RECORD\s0 is serialized by the wheel's associated POE::Filter so that it
will be ready to transmit.  The serialized stream may be transmitted
immediately by the wheel's POE::Driver object, or it may be buffered
in the POE::Driver until it can be flushed to the output filehandle.
.PP
Most wheels use POE::Filter::Line and POE::Driver::SysRW by default,
so it's not necessary to specify them in most cases.
.SS "Class Static Functions"
.IX Subsection "Class Static Functions"
These functions expose information that is common to all wheels.  They
are not methods, so they should \fBnot\fR be called as methods.
.PP
.Vb 2
\&  my $new_wheel_id = POE::Wheel::allocate_wheel_id();
\&  POE::Wheel::free_wheel_id($new_wheel_id);
.Ve
.PP
\fIallocate_wheel_id\fR
.IX Subsection "allocate_wheel_id"
.PP
\&\fBThis is not a class method.\fR
.PP
Every wheel has a unique \s-1ID.\s0  \fBallocate_wheel_id()\fR returns the next
available unique wheel \s-1ID.\s0  Wheel constructors use it to set their IDs
internally.
.PP
.Vb 2
\&  package POE::Wheel::Example;
\&  use base qw(POE::Wheel);
\&
\&  sub new {
\&    # ... among other things ...
\&    $self\->[MY_WHEEL_ID] = POE::Wheel::allocate_wheel_id();
\&    return $self;
\&  }
.Ve
.PP
Wheel IDs are used to tell apart events from similarly typed wheels.
For example, a multi-file tail utility may handle all file input with
the same function.  Wheel IDs may be used to tell which wheel
generated the InputEvent being handled.
.PP
Wheel IDs are often used to store wheel-local state in a session's
heap.
.PP
.Vb 5
\&  sub handle_error {
\&    my $wheel_id = $_[ARG3];
\&    print "Wheel $wheel_id caught an error.  Shutting it down.\en";
\&    delete $_[HEAP]{wheels}{$wheel_id};
\&  }
.Ve
.PP
It is vital for wheels to free their allocated IDs when they are
destroyed.  POE::Wheel class keeps track of allocated wheel IDs to
avoid collisions, and they will remain in memory until freed.  See
\&\fBfree_wheel_id()\fR.
.PP
\fIfree_wheel_id \s-1WHEEL_ID\s0\fR
.IX Subsection "free_wheel_id WHEEL_ID"
.PP
\&\fBThis is not a class method.\fR
.PP
\&\fBfree_wheel_id()\fR deallocates a wheel's \s-1ID\s0 so that it stops consuming
memory and may be reused later.  This is often called from a wheel's
destructor.
.PP
.Vb 2
\&  package POE::Wheel::Example;
\&  use base qw(POE::Wheel);
\&
\&  sub DESTROY {
\&    my $self = shift;
\&    # ... among other things ...
\&    POE::Wheel::free_wheel_id($self\->[MY_WHEEL_ID]);
\&  }
.Ve
.PP
Wheel IDs may be reused, although it has never been reported.  Two
active wheels will never share the same \s-1ID,\s0 however.
.PP
\fI\s-1ID\s0\fR
.IX Subsection "ID"
.PP
\&\fBThis is usually implemented in the subclass!\fR
.PP
The \s-1\fBID\s0()\fR method returns a wheel's unique \s-1ID.\s0 It is commonly used to
match events with the wheels which generated them.
.PP
Again, this method is not implemented in this class! If it's missing
from the subclass, please go pester that module author\-\-\-thanks!
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The \s-1SEE ALSO\s0 section in \s-1POE\s0 contains a table of contents covering
the entire \s-1POE\s0 distribution.
.PP
POE::Driver \- A base class for file access drivers that POE::Wheel
may use.
.PP
POE::Filter \- A base class for data parsers and marshalers that
POE::Wheel may use.
.PP
POE::Wheel::Curses \- Non-blocking input for Curses.
.PP
POE::Wheel::FollowTail \- Non-blocking file and \s-1FIFO\s0 monitoring.
.PP
POE::Wheel::ListenAccept \- Non-blocking server for existing
sockets.
.PP
POE::Wheel::ReadLine \- Non-blocking console input, with full
readline support.
.PP
POE::Wheel::ReadWrite \- Non-blocking stream I/O.
.PP
POE::Wheel::Run \- Non-blocking process creation and management.
.PP
POE::Wheel::SocketFactory \- Non-blocking socket creation,
supporting most protocols and modes.
.SH "BUGS"
.IX Header "BUGS"
It would be nice if wheels were more like proper Unix streams.
.SH "AUTHORS & COPYRIGHTS"
.IX Header "AUTHORS & COPYRIGHTS"
Please see \s-1POE\s0 for more information about authors, contributors,
and \s-1POE\s0;s licensing.