IO::Async::Handle(3pm)

1IO::Async::Handle(3)  User Contributed Perl Documentation IO::Async::Handle(3)
2
3
4

NAME

6       "IO::Async::Handle" - event callbacks for a non-blocking file
7       descriptor
8

SYNOPSIS

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
15          use IO::Socket::INET;
16          use IO::Async::Handle;
17
18          use IO::Async::Loop;
19          my $loop = IO::Async::Loop->new;
20
21          my $socket = IO::Socket::INET->new( LocalPort => 1234, Listen => 1 );
22
23          my $handle = IO::Async::Handle->new(
24             handle => $socket,
25
26             on_read_ready  => sub {
27                my $new_client = $socket->accept;
28                ...
29             },
30          );
31
32          $loop->add( $handle );
33
34       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. For non-stream sockets, see IO::Async::Socket.
37

DESCRIPTION

39       This subclass of IO::Async::Notifier allows non-blocking IO on
40       filehandles.  It provides event handlers for when the filehandle is
41       read- or write-ready.
42

EVENTS

44       The following events are invoked, either using subclass methods or CODE
45       references in parameters:
46
47   on_read_ready
48       Invoked when the read handle becomes ready for reading.
49
50   on_write_ready
51       Invoked when the write handle becomes ready for writing.
52
53   on_closed
54       Optional. Invoked when the handle becomes closed.
55
56       This handler is invoked before the filehandles are closed and the
57       Handle removed from its containing Loop. The "loop" will still return
58       the containing Loop object.
59

PARAMETERS

61       The following named parameters may be passed to "new" or "configure":
62
63   read_handle => IO
64   write_handle => IO
65       The reading and writing IO handles. Each must implement the "fileno"
66       method.  Primarily used for passing "STDIN" / "STDOUT"; see the
67       SYNOPSIS section of IO::Async::Stream for an example.
68
69   handle => IO
70       The IO handle for both reading and writing; instead of passing each
71       separately as above. Must implement "fileno" method in way that
72       "IO::Handle" does.
73
74   read_fileno => INT
75   write_fileno => INT
76       File descriptor numbers for reading and writing. If these are given as
77       an alternative to "read_handle" or "write_handle" then a new
78       "IO::Handle" instance will be constructed around each.
79
80   on_read_ready => CODE
81   on_write_ready => CODE
82   on_closed => CODE
83       CODE references for event handlers.
84
85   want_readready => BOOL
86   want_writeready => BOOL
87       If present, enable or disable read- or write-ready notification as per
88       the "want_readready" and "want_writeready" methods.
89
90       It is required that a matching "on_read_ready" or "on_write_ready" are
91       available for any handle that is provided; either passed as a callback
92       CODE reference or as an overridden the method. I.e. if only a
93       "read_handle" is given, then "on_write_ready" can be absent. If
94       "handle" is used as a shortcut, then both read and write-ready
95       callbacks or methods are required.
96
97       If no IO handles are provided at construction time, the object is still
98       created but will not yet be fully-functional as a Handle. IO handles
99       can be assigned later using the "set_handle" or "set_handles" methods,
100       or by "configure". This may be useful when constructing an object to
101       represent a network connection, before the connect(2) has actually been
102       performed yet.
103

METHODS

105       The following methods documented with a trailing call to "->get" return
106       Future instances.
107
108   set_handle
109          $handle->set_handles( %params )
110
111       Sets new reading or writing filehandles. Equivalent to calling the
112       "configure" method with the same parameters.
113
114   set_handle
115          $handle->set_handle( $fh )
116
117       Shortcut for
118
119          $handle->configure( handle => $fh )
120
121   close
122          $handle->close
123
124       This method calls "close" on the underlying IO handles. This method
125       will then remove the handle from its containing loop.
126
127   close_read
128   close_write
129          $handle->close_read
130
131          $handle->close_write
132
133       Closes the underlying read or write handle, and deconfigures it from
134       the object. Neither of these methods will invoke the "on_closed" event,
135       nor remove the object from the Loop if there is still one open handle
136       in the object. Only when both handles are closed, will "on_closed" be
137       fired, and the object removed.
138
139   new_close_future
140          $handle->new_close_future->get
141
142       Returns a new IO::Async::Future object which will become done when the
143       handle is closed. Cancelling the $future will remove this notification
144       ability but will not otherwise affect the $handle.
145
146   read_handle
147   write_handle
148          $handle = $handle->read_handle
149
150          $handle = $handle->write_handle
151
152       These accessors return the underlying IO handles.
153
154   read_fileno
155   write_fileno
156          $fileno = $handle->read_fileno
157
158          $fileno = $handle->write_fileno
159
160       These accessors return the file descriptor numbers of the underlying IO
161       handles.
162
163   want_readready
164   want_writeready
165          $value = $handle->want_readready
166
167          $oldvalue = $handle->want_readready( $newvalue )
168
169          $value = $handle->want_writeready
170
171          $oldvalue = $handle->want_writeready( $newvalue )
172
173       These are the accessor for the "want_readready" and "want_writeready"
174       properties, which define whether the object is interested in knowing
175       about read- or write-readiness on the underlying file handle.
176
177   socket
178          $handle->socket( $ai )
179
180       Convenient shortcut to creating a socket handle, as given by an
181       addrinfo structure, and setting it as the read and write handle for the
182       object.
183
184       $ai may be either a "HASH" or "ARRAY" reference of the same form as
185       given to IO::Async::OS's "extract_addrinfo" method.
186
187       This method returns nothing if it succeeds, or throws an exception if
188       it fails.
189
190   bind
191          $handle = $handle->bind( %args )->get
192
193       Performs a "getaddrinfo" resolver operation with the "passive" flag
194       set, and then attempts to bind a socket handle of any of the return
195       values.
196
197   bind (1 argument)
198          $handle = $handle->bind( $ai )->get
199
200       When invoked with a single argument, this method is a convenient
201       shortcut to creating a socket handle and bind()ing it to the address as
202       given by an addrinfo structure, and setting it as the read and write
203       handle for the object.
204
205       $ai may be either a "HASH" or "ARRAY" reference of the same form as
206       given to IO::Async::OS's "extract_addrinfo" method.
207
208       The returned future returns the handle object itself for convenience.
209
210   connect
211          $handle = $handle->connect( %args )->get
212
213       A convenient wrapper for calling the "connect" method on the underlying
214       IO::Async::Loop object.
215

AUTHOR

220       Paul Evans <leonerd@leonerd.org.uk>
221
222
223
224perl v5.36.0                      2023-01-20              IO::Async::Handle(3)