1IO::Async::Handle(3) User Contributed Perl Documentation IO::Async::Handle(3)
2
6 "IO::Async::Handle" - event callbacks for a non-blocking file
7 descriptor
8
10 This class is likely not to be used directly, because subclasses of it
11 exist to handle more specific cases. Here is an example of how it would
12 be used to watch a listening socket for new connections. In real code,
13 it is likely that the "Loop->listen()" method would be used instead.
14 use IO::Socket::INET;
16 use IO::Async::Handle;
17 use IO::Async::Loop;
19 my $loop = IO::Async::Loop->new();
20 my $socket = IO::Socket::INET->new( LocalPort => 1234, Listen => 1 );
22 my $handle = IO::Async::Handle->new(
24 handle => $socket,
25 on_read_ready => sub {
27 my $new_client = $socket->accept();
28 ...
29 },
30 );
31 $loop->add( $handle );
33 For most other uses with sockets, pipes or other filehandles that carry
35 a byte stream, the "IO::Async::Stream" class is likely to be more
36 suitable.
37
39 This module provides a class of "IO::Async::Notifier" for implementing
40 non-blocking IO on file descriptors. The object interacts with the
41 actual OS by being part of the "IO::Async::Loop" object it has been
42 added to.
43 This object may be used in one of two ways; with callback functions, or
45 as a base class.
46 Callbacks
48 If the "on_read_ready" or "on_write_ready" keys are supplied in the
49 constructor, they should contain CODE references to callback
50 functions to be called when the underlying IO handle becomes
51 readable or writable:
52 $on_read_ready->( $self )
54 $on_write_ready->( $self )
56 Optionally, an "on_closed" key can also be specified, which will be
58 called when the "close" method is invoked.
59 $on_closed->( $self )
61 This callback is invoked before the filehandles are closed and the
63 Handle removed from its containing Loop. The "get_loop" will still
64 return the containing Loop object.
65 Base Class
67 If a subclass is built, then it can override the "on_read_ready" or
68 "on_write_ready" methods of the base to perform its work. In this
69 case, it should not call the "SUPER::" versions of those methods.
70 $self->on_read_ready()
72 $self->on_write_ready()
74 Optionally, an "on_closed" method may be provided, which will be
76 called when the "close" method is invoked.
77 $self->on_closed()
79 If either of the readyness methods calls the "close()" method, then the
81 handle is internally marked as closed within the object and will be
82 removed from its containing loop, if it is within one.
83
85 The following named parameters may be passed to "new" or "configure":
86 read_handle => IO
88 write_handle => IO
89 The reading and writing IO handles. Each must implement the
90 "fileno" method. Primarily used for passing "STDIN" /
91 "STDOUT"; see the SYNOPSIS section of "IO::Async::Stream" for
92 an example.
93 handle => IO
95 The IO handle for both reading and writing; instead of passing
96 each separately as above. Must implement "fileno" method in way
97 that "IO::Handle" does.
98 on_read_ready => CODE
100 on_write_ready => CODE
101 CODE references to callbacks for when the handle becomes read-
102 ready or write-ready. If these are not supplied, subclass
103 methods will be called instead.
104 on_closed => CODE
106 CODE reference to the callback for when the handle becomes
107 closed.
108 It is required that a matching "on_read_ready" or "on_write_ready" are
110 available for any handle that is provided; either passed as a callback
111 CODE reference or as an overridden the method. I.e. if only a
112 "read_handle" is given, then "on_write_ready" can be absent. If
113 "handle" is used as a shortcut, then both read and write-ready
114 callbacks or methods are required.
115 If no IO handles are provided at construction time, the object is still
117 created but will not yet be fully-functional as a Handle. IO handles
118 can be assigned later using the "set_handle" or "set_handles" methods.
119 This may be useful when constructing an object to represent a network
120 connection, before the "connect()" has actually been performed yet.
121
123 $handle->set_handles( %params )
124 Sets new reading or writing filehandles. Equivalent to calling the
125 "configure" method with the same parameters.
126 $handle->set_handle( $fh )
128 Shortcut for
129 $handle->configure( handle => $fh )
131 $handle->close
133 This method calls "close" on the underlying IO handles. This method
134 will then remove the handle from its containing loop.
135 $handle = $handle->read_handle
137 $handle = $handle->write_handle
138 These accessors return the underlying IO handles.
139 $fileno = $handle->read_fileno
141 $fileno = $handle->write_fileno
142 These accessors return the file descriptor numbers of the underlying IO
143 handles.
144 $value = $handle->want_readready
146 $oldvalue = $handle->want_readready( $newvalue )
147 $value = $handle->want_writeready
148 $oldvalue = $handle->want_writeready( $newvalue )
149 These are the accessor for the "want_readready" and "want_writeready"
150 properties, which define whether the object is interested in knowing
151 about read- or write-readiness on the underlying file handle.
152
154 ยท IO::Handle - Supply object methods for I/O handles
155
157 Paul Evans <leonerd@leonerd.org.uk>
158perl v5.12.1 2010-06-09 IO::Async::Handle(3)