1IO::Async::Notifier(3)User Contributed Perl DocumentationIO::Async::Notifier(3)
2
6 "IO::Async::Notifier" - base class for IO::Async event objects
7
9 Usually not directly used by a program, but one valid use case may be:
10 use IO::Async::Notifier;
12 use IO::Async::Stream;
14 use IO::Async::Signal;
15 use IO::Async::Loop;
17 my $loop = IO::Async::Loop->new;
18 my $notifier = IO::Async::Notifier->new;
20 $notifier->add_child(
22 IO::Async::Stream->new_for_stdin(
23 on_read => sub {
24 my $self = shift;
25 my ( $buffref, $eof ) = @_;
26 while( $$buffref =~ s/^(.*)\n// ) {
28 print "You said $1\n";
29 }
30 return 0;
32 },
33 )
34 );
35 $notifier->add_child(
37 IO::Async::Signal->new(
38 name => 'INT',
39 on_receipt => sub {
40 print "Goodbye!\n";
41 $loop->stop;
42 },
43 )
44 );
45 $loop->add( $notifier );
47 $loop->run;
49
51 This object class forms the basis for all the other event objects that
52 an IO::Async program uses. It provides the lowest level of integration
53 with a IO::Async::Loop container, and a facility to collect Notifiers
54 together, in a tree structure, where any Notifier can contain a
55 collection of children.
56 Normally, objects in this class would not be directly used by an end
58 program, as it performs no actual IO work, and generates no actual
59 events. These are all left to the various subclasses, such as:
60 • IO::Async::Handle - event callbacks for a non-blocking file
62 descriptor
63 • IO::Async::Stream - event callbacks and write bufering for a stream
65 filehandle
66 • IO::Async::Socket - event callbacks and send buffering for a socket
68 filehandle
69 • IO::Async::Timer - base class for Notifiers that use timed delays
71 • IO::Async::Signal - event callback on receipt of a POSIX signal
73 • IO::Async::PID - event callback on exit of a child process
75 • IO::Async::Process - start and manage a child process
77 For more detail, see the SYNOPSIS section in one of the above.
79 One case where this object class would be used, is when a library
81 wishes to provide a sub-component which consists of multiple other
82 "Notifier" subclasses, such as "Handle"s and "Timers", but no
83 particular object is suitable to be the root of a tree. In this case, a
84 plain "Notifier" object can be used as the tree root, and all the other
85 notifiers added as children of it.
86
88 Rather than being used as a subclass this package also supports being
89 used as a non-principle superclass for an object, as a mix-in. It still
90 provides methods and satisfies an "isa" test, even though the
91 constructor is not directly called. This simply requires that the
92 object be based on a normal blessed hash reference and include
93 "IO::Async::Notifier" somewhere in its @ISA list.
94 The methods in this class all use only keys in the hash prefixed by
96 "IO_Async_Notifier__" for namespace purposes.
97 This is intended mainly for defining a subclass of some other object
99 that is also an "IO::Async::Notifier", suitable to be added to an
100 IO::Async::Loop.
101 package SomeEventSource::Async;
103 use base qw( SomeEventSource IO::Async::Notifier );
104 sub _add_to_loop
106 {
107 my $self = shift;
108 my ( $loop ) = @_;
109 # Code here to set up event handling on $loop that may be required
111 }
112 sub _remove_from_loop
114 {
115 my $self = shift;
116 my ( $loop ) = @_;
117 # Code here to undo the event handling set up above
119 }
120 Since all the methods documented here will be available, the
122 implementation may wish to use the "configure" and "make_event_cb" or
123 "invoke_event" methods to implement its own event callbacks.
124
126 The following events are invoked, either using subclass methods or CODE
127 references in parameters:
128 on_error $message, $name, @details
130 Invoked by "invoke_error".
131
133 A specific subclass of "IO::Async::Notifier" defines named parameters
134 that control its behaviour. These may be passed to the "new"
135 constructor, or to the "configure" method. The documentation on each
136 specific subclass will give details on the parameters that exist, and
137 their uses. Some parameters may only support being set once at
138 construction time, or only support being changed if the object is in a
139 particular state.
140 The following parameters are supported by all Notifiers:
142 on_error => CODE
144 CODE reference for event handler.
145 notifier_name => STRING
147 Optional string used to identify this particular Notifier. This
148 value will be returned by the "notifier_name" method.
149
151 new
152 $notifier = IO::Async::Notifier->new( %params )
153 This function returns a new instance of a "IO::Async::Notifier" object
155 with the given initial values of the named parameters.
156 Up until IO::Async version 0.19, this module used to implement the IO
158 handle features now found in the IO::Async::Handle subclass. Code that
159 needs to use any of "handle", "read_handle", "write_handle",
160 "on_read_ready" or "on_write_ready" should use IO::Async::Handle
161 instead.
162
164 configure
165 $notifier->configure( %params )
166 Adjust the named parameters of the "Notifier" as given by the %params
168 hash.
169 loop
171 $loop = $notifier->loop
172 Returns the IO::Async::Loop that this Notifier is a member of.
174 notifier_name
176 $name = $notifier->notifier_name
177 Returns the name to identify this Notifier. If a has not been set, it
179 will return the empty string. Subclasses may wish to override this
180 behaviour to return some more useful information, perhaps from
181 configured parameters.
182 adopt_future
184 $f = $notifier->adopt_future( $f )
185 Stores a reference to the Future instance within the notifier itself,
187 so the reference doesn't get lost. This reference will be dropped when
188 the future becomes ready (either by success or failure). Additionally,
189 if the future failed the notifier's "invoke_error" method will be
190 informed.
191 This means that if the notifier does not provide an "on_error" handler,
193 nor is there one anywhere in the parent chain, this will be fatal to
194 the caller of "$f->fail". To avoid this being fatal if the failure is
195 handled elsewhere, use the "else_done" method on the future to obtain a
196 sequence one that never fails.
197 $notifier->adopt_future( $f->else_done() )
199 The future itself is returned.
201 adopted_futures
203 @f = $notifier->adopted_futures
204 Since version 0.73.
206 Returns a list of all the adopted and still-pending futures, in no
208 particular order.
209
211 During the execution of a program, it may be the case that certain IO
212 handles cause other handles to be created; for example, new sockets
213 that have been "accept()"ed from a listening socket. To facilitate
214 these, a notifier may contain child notifier objects, that are
215 automatically added to or removed from the IO::Async::Loop that manages
216 their parent.
217 parent
219 $parent = $notifier->parent
220 Returns the parent of the notifier, or "undef" if does not have one.
222 children
224 @children = $notifier->children
225 Returns a list of the child notifiers contained within this one.
227 add_child
229 $notifier->add_child( $child )
230 Adds a child notifier. This notifier will be added to the containing
232 loop, if the parent has one. Only a notifier that does not currently
233 have a parent and is not currently a member of any loop may be added as
234 a child. If the child itself has grandchildren, these will be
235 recursively added to the containing loop.
236 remove_child
238 $notifier->remove_child( $child )
239 Removes a child notifier. The child will be removed from the containing
241 loop, if the parent has one. If the child itself has grandchildren,
242 these will be recurively removed from the loop.
243 remove_from_parent
245 $notifier->remove_from_parent
246 Removes this notifier object from its parent (either another notifier
248 object or the containing loop) if it has one. If the notifier is not a
249 child of another notifier nor a member of a loop, this method does
250 nothing.
251
253 "IO::Async::Notifier" is a base class provided so that specific
254 subclasses of it provide more specific behaviour. The base class
255 provides a number of methods that subclasses may wish to override.
256 If a subclass implements any of these, be sure to invoke the superclass
258 method at some point within the code.
259 _init
261 $notifier->_init( $paramsref )
262 This method is called by the constructor just before calling
264 "configure". It is passed a reference to the HASH storing the
265 constructor arguments.
266 This method may initialise internal details of the Notifier as
268 required, possibly by using parameters from the HASH. If any parameters
269 are construction-only they should be "delete"d from the hash.
270 configure
272 $notifier->configure( %params )
273 This method is called by the constructor to set the initial values of
275 named parameters, and by users of the object to adjust the values once
276 constructed.
277 This method should "delete" from the %params hash any keys it has dealt
279 with, then pass the remaining ones to the "SUPER::configure". The base
280 class implementation will throw an exception if there are any
281 unrecognised keys remaining.
282 configure_unknown
284 $notifier->configure_unknown( %params )
285 This method is called by the base class "configure" method, for any
287 remaining parameters that are not recognised. The default
288 implementation throws an exception using "Carp" that lists the
289 unrecognised keys. This method is provided to allow subclasses to
290 override the behaviour, perhaps to store unrecognised keys, or to
291 otherwise inspect the left-over arguments for some other purpose.
292 _add_to_loop
294 $notifier->_add_to_loop( $loop )
295 This method is called when the Notifier has been added to a Loop;
297 either directly, or indirectly through being a child of a Notifer
298 already in a loop.
299 This method may be used to perform any initial startup activity
301 required for the Notifier to be fully functional but which requires a
302 Loop to do so.
303 _remove_from_loop
305 $notifier->_remove_from_loop( $loop )
306 This method is called when the Notifier has been removed from a Loop;
308 either directly, or indirectly through being a child of a Notifier
309 removed from the loop.
310 This method may be used to undo the effects of any setup that the
312 "_add_to_loop" method had originally done.
313
315 _capture_weakself
316 $mref = $notifier->_capture_weakself( $code )
317 Returns a new CODE ref which, when invoked, will invoke the originally-
319 passed ref, with additionally a reference to the Notifier as its first
320 argument. The Notifier reference is stored weakly in $mref, so this
321 CODE ref may be stored in the Notifier itself without creating a cycle.
322 For example,
324 my $mref = $notifier->_capture_weakself( sub {
326 my ( $notifier, $arg ) = @_;
327 print "Notifier $notifier got argument $arg\n";
328 } );
329 $mref->( 123 );
331 This is provided as a utility for Notifier subclasses to use to build a
333 callback CODEref to pass to a Loop method, but which may also want to
334 store the CODE ref internally for efficiency.
335 The $code argument may also be a plain string, which will be used as a
337 method name; the returned CODE ref will then invoke that method on the
338 object. In this case the method name is stored symbolically in the
339 returned CODE reference, and dynamically dispatched each time the
340 reference is invoked. This allows it to follow code reloading, dynamic
341 replacement of class methods, or other similar techniques.
342 If the $mref CODE reference is being stored in some object other than
344 the one it refers to, remember that since the Notifier is only weakly
345 captured, it is possible that it has been destroyed by the time the
346 code runs, and so the reference will be passed as "undef". This should
347 be protected against by the code body.
348 $other_object->{on_event} = $notifier->_capture_weakself( sub {
350 my $notifier = shift or return;
351 my ( @event_args ) = @_;
352 ...
353 } );
354 For stand-alone generic implementation of this behaviour, see also
356 curry and "curry::weak".
357 _replace_weakself
359 $mref = $notifier->_replace_weakself( $code )
360 Returns a new CODE ref which, when invoked, will invoke the originally-
362 passed ref, with a reference to the Notifier replacing its first
363 argument. The Notifier reference is stored weakly in $mref, so this
364 CODE ref may be stored in the Notifier itself without creating a cycle.
365 For example,
367 my $mref = $notifier->_replace_weakself( sub {
369 my ( $notifier, $arg ) = @_;
370 print "Notifier $notifier got argument $arg\n";
371 } );
372 $mref->( $object, 123 );
374 This is provided as a utility for Notifier subclasses to use for event
376 callbacks on other objects, where the delegated object is passed in the
377 function's arguments.
378 The $code argument may also be a plain string, which will be used as a
380 method name; the returned CODE ref will then invoke that method on the
381 object. As with "_capture_weakself" this is stored symbolically.
382 As with "_capture_weakself", care should be taken against Notifier
384 destruction if the $mref CODE reference is stored in some other object.
385 can_event
387 $code = $notifier->can_event( $event_name )
388 Returns a "CODE" reference if the object can perform the given event
390 name, either by a configured "CODE" reference parameter, or by
391 implementing a method. If the object is unable to handle this event,
392 "undef" is returned.
393 make_event_cb
395 $callback = $notifier->make_event_cb( $event_name )
396 Returns a "CODE" reference which, when invoked, will execute the given
398 event handler. Event handlers may either be subclass methods, or
399 parameters given to the "new" or "configure" method.
400 The event handler can be passed extra arguments by giving them to the
402 "CODE" reference; the first parameter received will be a reference to
403 the notifier itself. This is stored weakly in the closure, so it is
404 safe to store the resulting "CODE" reference in the object itself
405 without causing a reference cycle.
406 maybe_make_event_cb
408 $callback = $notifier->maybe_make_event_cb( $event_name )
409 Similar to "make_event_cb" but will return "undef" if the object cannot
411 handle the named event, rather than throwing an exception.
412 invoke_event
414 @ret = $notifier->invoke_event( $event_name, @args )
415 Invokes the given event handler, passing in the given arguments. Event
417 handlers may either be subclass methods, or parameters given to the
418 "new" or "configure" method. Returns whatever the underlying method or
419 CODE reference returned.
420 maybe_invoke_event
422 $retref = $notifier->maybe_invoke_event( $event_name, @args )
423 Similar to "invoke_event" but will return "undef" if the object cannot
425 handle the name event, rather than throwing an exception. In order to
426 distinguish this from an event-handling function that simply returned
427 "undef", if the object does handle the event, the list that it returns
428 will be returned in an ARRAY reference.
429
431 debug_printf
432 $notifier->debug_printf( $format, @args )
433 Conditionally print a debugging message to "STDERR" if debugging is
435 enabled. If such a message is printed, it will be printed using
436 "printf" using the given format and arguments. The message will be
437 prefixed with a string, in square brackets, to help identify the
438 $notifier instance. This string will be the class name of the notifier,
439 and any parent notifiers it is contained by, joined by an arrow "<-".
440 To ensure this string does not grow too long, certain prefixes are
441 abbreviated:
442 IO::Async::Protocol:: => IaP:
444 IO::Async:: => Ia:
445 Net::Async:: => Na:
446 Finally, each notifier that has a name defined using the
448 "notifier_name" parameter has that name appended in braces.
449 For example, invoking
451 $stream->debug_printf( "EVENT on_read" )
453 On an IO::Async::Stream instance reading and writing a file descriptor
455 whose "fileno" is 4, which is a child of an
456 IO::Async::Protocol::Stream, will produce a line of output:
457 [Ia:Stream{rw=4}<-IaP:Stream] EVENT on_read
459 invoke_error
461 $notifier->invoke_error( $message, $name, @details )
462 Invokes the stored "on_error" event handler, passing in the given
464 arguments. If no handler is defined, it will be passed up to the
465 containing parent notifier, if one exists. If no parent exists, the
466 error message will be thrown as an exception by using "die()" and this
467 method will not return.
468 If a handler is found to handle this error, the method will return as
470 normal. However, as the expected use-case is to handle "fatal" errors
471 that now render the notifier unsuitable to continue, code should be
472 careful not to perform any further work after invoking it.
473 Specifically, sockets may become disconnected, or the entire notifier
474 may now be removed from its containing loop.
475 The $name and @details list should follow similar semantics to Future
477 failures. That is, the $name should be a string giving a category of
478 failure, and the @details list should contain additional arguments that
479 relate to that kind of failure.
480
482 Paul Evans <leonerd@leonerd.org.uk>
483perl v5.34.0 2022-01-21 IO::Async::Notifier(3)