.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IO::Async::Handle 3pm"
.TH IO::Async::Handle 3pm "2012-10-24" "perl v5.14.2" "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"
"IO::Async::Handle" \- event callbacks for a non\-blocking file descriptor
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
This class is likely not to be used directly, because subclasses of it exist
to handle more specific cases. Here is an example of how it would be used to
watch a listening socket for new connections. In real code, it is likely that
the \f(CW\*(C`Loop\->listen\*(C'\fR method would be used instead.
.PP
.Vb 2
\& use IO::Socket::INET;
\& use IO::Async::Handle;
\&
\& use IO::Async::Loop;
\& my $loop = IO::Async::Loop\->new;
\&
\& my $socket = IO::Socket::INET\->new( LocalPort => 1234, Listen => 1 );
\&
\& my $handle = IO::Async::Handle\->new(
\&    handle => $socket,
\&
\&    on_read_ready  => sub {
\&       my $new_client = $socket\->accept; 
\&       ...
\&    },
\& );
\&
\& $loop\->add( $handle );
.Ve
.PP
For most other uses with sockets, pipes or other filehandles that carry a byte
stream, the IO::Async::Stream class is likely to be more suitable. For
non-stream sockets, see IO::Async::Socket.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This subclass of IO::Async::Notifier allows non-blocking \s-1IO\s0 on filehandles.
It provides event handlers for when the filehandle is read\- or write-ready.
.SH "EVENTS"
.IX Header "EVENTS"
The following events are invoked, either using subclass methods or \s-1CODE\s0
references in parameters:
.SS "on_read_ready"
.IX Subsection "on_read_ready"
Invoked when the read handle becomes ready for reading.
.SS "on_write_ready"
.IX Subsection "on_write_ready"
Invoked when the write handle becomes ready for writing.
.SS "on_closed"
.IX Subsection "on_closed"
Optional. Invoked when the handle becomes closed.
.PP
This handler is invoked before the filehandles are closed and the Handle
removed from its containing Loop. The \f(CW\*(C`loop\*(C'\fR will still return the containing
Loop object.
.SH "PARAMETERS"
.IX Header "PARAMETERS"
The following named parameters may be passed to \f(CW\*(C`new\*(C'\fR or \f(CW\*(C`configure\*(C'\fR:
.IP "read_handle => \s-1IO\s0" 8
.IX Item "read_handle => IO"
.PD 0
.IP "write_handle => \s-1IO\s0" 8
.IX Item "write_handle => IO"
.PD
The reading and writing \s-1IO\s0 handles. Each must implement the \f(CW\*(C`fileno\*(C'\fR method.
Primarily used for passing \f(CW\*(C`STDIN\*(C'\fR / \f(CW\*(C`STDOUT\*(C'\fR; see the \s-1SYNOPSIS\s0 section of
\&\f(CW\*(C`IO::Async::Stream\*(C'\fR for an example.
.IP "handle => \s-1IO\s0" 8
.IX Item "handle => IO"
The \s-1IO\s0 handle for both reading and writing; instead of passing each separately
as above. Must implement \f(CW\*(C`fileno\*(C'\fR method in way that \f(CW\*(C`IO::Handle\*(C'\fR does.
.IP "on_read_ready => \s-1CODE\s0" 8
.IX Item "on_read_ready => CODE"
.PD 0
.IP "on_write_ready => \s-1CODE\s0" 8
.IX Item "on_write_ready => CODE"
.IP "on_closed => \s-1CODE\s0" 8
.IX Item "on_closed => CODE"
.PD
\&\s-1CODE\s0 references for event handlers.
.IP "want_readready => \s-1BOOL\s0" 8
.IX Item "want_readready => BOOL"
.PD 0
.IP "want_writeready => \s-1BOOL\s0" 8
.IX Item "want_writeready => BOOL"
.PD
If present, enable or disable read\- or write-ready notification as per the
\&\f(CW\*(C`want_readready\*(C'\fR and \f(CW\*(C`want_writeready\*(C'\fR methods.
.PP
It is required that a matching \f(CW\*(C`on_read_ready\*(C'\fR or \f(CW\*(C`on_write_ready\*(C'\fR are
available for any handle that is provided; either passed as a callback \s-1CODE\s0
reference or as an overridden the method. I.e. if only a \f(CW\*(C`read_handle\*(C'\fR is
given, then \f(CW\*(C`on_write_ready\*(C'\fR can be absent. If \f(CW\*(C`handle\*(C'\fR is used as a
shortcut, then both read and write-ready callbacks or methods are required.
.PP
If no \s-1IO\s0 handles are provided at construction time, the object is still
created but will not yet be fully-functional as a Handle. \s-1IO\s0 handles can be
assigned later using the \f(CW\*(C`set_handle\*(C'\fR or \f(CW\*(C`set_handles\*(C'\fR methods, or by
\&\f(CW\*(C`configure\*(C'\fR. This may be useful when constructing an object to represent a
network connection, before the \f(CWconnect(2)\fR has actually been performed yet.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$handle\->set_handles( %params )"
.el .SS "\f(CW$handle\fP\->set_handles( \f(CW%params\fP )"
.IX Subsection "$handle->set_handles( %params )"
Sets new reading or writing filehandles. Equivalent to calling the
\&\f(CW\*(C`configure\*(C'\fR method with the same parameters.
.ie n .SS "$handle\->set_handle( $fh )"
.el .SS "\f(CW$handle\fP\->set_handle( \f(CW$fh\fP )"
.IX Subsection "$handle->set_handle( $fh )"
Shortcut for
.PP
.Vb 1
\& $handle\->configure( handle => $fh )
.Ve
.ie n .SS "$handle\->close"
.el .SS "\f(CW$handle\fP\->close"
.IX Subsection "$handle->close"
This method calls \f(CW\*(C`close\*(C'\fR on the underlying \s-1IO\s0 handles. This method will then
remove the handle from its containing loop.
.ie n .SS "$handle\->close_read"
.el .SS "\f(CW$handle\fP\->close_read"
.IX Subsection "$handle->close_read"
.ie n .SS "$handle\->close_write"
.el .SS "\f(CW$handle\fP\->close_write"
.IX Subsection "$handle->close_write"
Closes the underlying read or write handle, and deconfigures it from the
object. Neither of these methods will invoke the \f(CW\*(C`on_closed\*(C'\fR event, nor
remove the object from the Loop if there is still one open handle in the
object. Only when both handles are closed, will \f(CW\*(C`on_closed\*(C'\fR be fired, and the
object removed.
.ie n .SS "$handle = $handle\->read_handle"
.el .SS "\f(CW$handle\fP = \f(CW$handle\fP\->read_handle"
.IX Subsection "$handle = $handle->read_handle"
.ie n .SS "$handle = $handle\->write_handle"
.el .SS "\f(CW$handle\fP = \f(CW$handle\fP\->write_handle"
.IX Subsection "$handle = $handle->write_handle"
These accessors return the underlying \s-1IO\s0 handles.
.ie n .SS "$fileno = $handle\->read_fileno"
.el .SS "\f(CW$fileno\fP = \f(CW$handle\fP\->read_fileno"
.IX Subsection "$fileno = $handle->read_fileno"
.ie n .SS "$fileno = $handle\->write_fileno"
.el .SS "\f(CW$fileno\fP = \f(CW$handle\fP\->write_fileno"
.IX Subsection "$fileno = $handle->write_fileno"
These accessors return the file descriptor numbers of the underlying \s-1IO\s0
handles.
.ie n .SS "$value = $handle\->want_readready"
.el .SS "\f(CW$value\fP = \f(CW$handle\fP\->want_readready"
.IX Subsection "$value = $handle->want_readready"
.ie n .SS "$oldvalue = $handle\->want_readready( $newvalue )"
.el .SS "\f(CW$oldvalue\fP = \f(CW$handle\fP\->want_readready( \f(CW$newvalue\fP )"
.IX Subsection "$oldvalue = $handle->want_readready( $newvalue )"
.ie n .SS "$value = $handle\->want_writeready"
.el .SS "\f(CW$value\fP = \f(CW$handle\fP\->want_writeready"
.IX Subsection "$value = $handle->want_writeready"
.ie n .SS "$oldvalue = $handle\->want_writeready( $newvalue )"
.el .SS "\f(CW$oldvalue\fP = \f(CW$handle\fP\->want_writeready( \f(CW$newvalue\fP )"
.IX Subsection "$oldvalue = $handle->want_writeready( $newvalue )"
These are the accessor for the \f(CW\*(C`want_readready\*(C'\fR and \f(CW\*(C`want_writeready\*(C'\fR
properties, which define whether the object is interested in knowing about 
read\- or write-readiness on the underlying file handle.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
IO::Handle \- Supply object methods for I/O handles
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>