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 these,
214 a notifier may contain child notifier objects, that are automatically
215 added to or removed from the IO::Async::Loop that manages their parent.
216 parent
218 $parent = $notifier->parent
219 Returns the parent of the notifier, or "undef" if does not have one.
221 children
223 @children = $notifier->children
224 Returns a list of the child notifiers contained within this one.
226 add_child
228 $notifier->add_child( $child )
229 Adds a child notifier. This notifier will be added to the containing
231 loop, if the parent has one. Only a notifier that does not currently
232 have a parent and is not currently a member of any loop may be added as
233 a child. If the child itself has grandchildren, these will be
234 recursively added to the containing loop.
235 remove_child
237 $notifier->remove_child( $child )
238 Removes a child notifier. The child will be removed from the containing
240 loop, if the parent has one. If the child itself has grandchildren,
241 these will be recurively removed from the loop.
242 remove_from_parent
244 $notifier->remove_from_parent
245 Removes this notifier object from its parent (either another notifier
247 object or the containing loop) if it has one. If the notifier is not a
248 child of another notifier nor a member of a loop, this method does
249 nothing.
250
252 "IO::Async::Notifier" is a base class provided so that specific
253 subclasses of it provide more specific behaviour. The base class
254 provides a number of methods that subclasses may wish to override.
255 If a subclass implements any of these, be sure to invoke the superclass
257 method at some point within the code.
258 _init
260 $notifier->_init( $paramsref )
261 This method is called by the constructor just before calling
263 "configure". It is passed a reference to the HASH storing the
264 constructor arguments.
265 This method may initialise internal details of the Notifier as
267 required, possibly by using parameters from the HASH. If any parameters
268 are construction-only they should be "delete"d from the hash.
269 configure
271 $notifier->configure( %params )
272 This method is called by the constructor to set the initial values of
274 named parameters, and by users of the object to adjust the values once
275 constructed.
276 This method should "delete" from the %params hash any keys it has dealt
278 with, then pass the remaining ones to the "SUPER::configure". The base
279 class implementation will throw an exception if there are any
280 unrecognised keys remaining.
281 configure_unknown
283 $notifier->configure_unknown( %params )
284 This method is called by the base class "configure" method, for any
286 remaining parameters that are not recognised. The default
287 implementation throws an exception using "Carp" that lists the
288 unrecognised keys. This method is provided to allow subclasses to
289 override the behaviour, perhaps to store unrecognised keys, or to
290 otherwise inspect the left-over arguments for some other purpose.
291 _add_to_loop
293 $notifier->_add_to_loop( $loop )
294 This method is called when the Notifier has been added to a Loop;
296 either directly, or indirectly through being a child of a Notifer
297 already in a loop.
298 This method may be used to perform any initial startup activity
300 required for the Notifier to be fully functional but which requires a
301 Loop to do so.
302 _remove_from_loop
304 $notifier->_remove_from_loop( $loop )
305 This method is called when the Notifier has been removed from a Loop;
307 either directly, or indirectly through being a child of a Notifier
308 removed from the loop.
309 This method may be used to undo the effects of any setup that the
311 "_add_to_loop" method had originally done.
312
314 _capture_weakself
315 $mref = $notifier->_capture_weakself( $code )
316 Returns a new CODE ref which, when invoked, will invoke the originally-
318 passed ref, with additionally a reference to the Notifier as its first
319 argument. The Notifier reference is stored weakly in $mref, so this
320 CODE ref may be stored in the Notifier itself without creating a cycle.
321 For example,
323 my $mref = $notifier->_capture_weakself( sub {
325 my ( $notifier, $arg ) = @_;
326 print "Notifier $notifier got argument $arg\n";
327 } );
328 $mref->( 123 );
330 This is provided as a utility for Notifier subclasses to use to build a
332 callback CODEref to pass to a Loop method, but which may also want to
333 store the CODE ref internally for efficiency.
334 The $code argument may also be a plain string, which will be used as a
336 method name; the returned CODE ref will then invoke that method on the
337 object. In this case the method name is stored symbolically in the
338 returned CODE reference, and dynamically dispatched each time the
339 reference is invoked. This allows it to follow code reloading, dynamic
340 replacement of class methods, or other similar techniques.
341 If the $mref CODE reference is being stored in some object other than
343 the one it refers to, remember that since the Notifier is only weakly
344 captured, it is possible that it has been destroyed by the time the
345 code runs, and so the reference will be passed as "undef". This should
346 be protected against by the code body.
347 $other_object->{on_event} = $notifier->_capture_weakself( sub {
349 my $notifier = shift or return;
350 my ( @event_args ) = @_;
351 ...
352 } );
353 For stand-alone generic implementation of this behaviour, see also
355 curry and "curry::weak".
356 _replace_weakself
358 $mref = $notifier->_replace_weakself( $code )
359 Returns a new CODE ref which, when invoked, will invoke the originally-
361 passed ref, with a reference to the Notifier replacing its first
362 argument. The Notifier reference is stored weakly in $mref, so this
363 CODE ref may be stored in the Notifier itself without creating a cycle.
364 For example,
366 my $mref = $notifier->_replace_weakself( sub {
368 my ( $notifier, $arg ) = @_;
369 print "Notifier $notifier got argument $arg\n";
370 } );
371 $mref->( $object, 123 );
373 This is provided as a utility for Notifier subclasses to use for event
375 callbacks on other objects, where the delegated object is passed in the
376 function's arguments.
377 The $code argument may also be a plain string, which will be used as a
379 method name; the returned CODE ref will then invoke that method on the
380 object. As with "_capture_weakself" this is stored symbolically.
381 As with "_capture_weakself", care should be taken against Notifier
383 destruction if the $mref CODE reference is stored in some other object.
384 can_event
386 $code = $notifier->can_event( $event_name )
387 Returns a "CODE" reference if the object can perform the given event
389 name, either by a configured "CODE" reference parameter, or by
390 implementing a method. If the object is unable to handle this event,
391 "undef" is returned.
392 make_event_cb
394 $callback = $notifier->make_event_cb( $event_name )
395 Returns a "CODE" reference which, when invoked, will execute the given
397 event handler. Event handlers may either be subclass methods, or
398 parameters given to the "new" or "configure" method.
399 The event handler can be passed extra arguments by giving them to the
401 "CODE" reference; the first parameter received will be a reference to
402 the notifier itself. This is stored weakly in the closure, so it is
403 safe to store the resulting "CODE" reference in the object itself
404 without causing a reference cycle.
405 maybe_make_event_cb
407 $callback = $notifier->maybe_make_event_cb( $event_name )
408 Similar to "make_event_cb" but will return "undef" if the object cannot
410 handle the named event, rather than throwing an exception.
411 invoke_event
413 @ret = $notifier->invoke_event( $event_name, @args )
414 Invokes the given event handler, passing in the given arguments. Event
416 handlers may either be subclass methods, or parameters given to the
417 "new" or "configure" method. Returns whatever the underlying method or
418 CODE reference returned.
419 maybe_invoke_event
421 $retref = $notifier->maybe_invoke_event( $event_name, @args )
422 Similar to "invoke_event" but will return "undef" if the object cannot
424 handle the name event, rather than throwing an exception. In order to
425 distinguish this from an event-handling function that simply returned
426 "undef", if the object does handle the event, the list that it returns
427 will be returned in an ARRAY reference.
428
430 debug_printf
431 $notifier->debug_printf( $format, @args )
432 Conditionally print a debugging message to "STDERR" if debugging is
434 enabled. If such a message is printed, it will be printed using
435 "printf" using the given format and arguments. The message will be
436 prefixed with a string, in square brackets, to help identify the
437 $notifier instance. This string will be the class name of the notifier,
438 and any parent notifiers it is contained by, joined by an arrow "<-".
439 To ensure this string does not grow too long, certain prefixes are
440 abbreviated:
441 IO::Async::Protocol:: => IaP:
443 IO::Async:: => Ia:
444 Net::Async:: => Na:
445 Finally, each notifier that has a name defined using the
447 "notifier_name" parameter has that name appended in braces.
448 For example, invoking
450 $stream->debug_printf( "EVENT on_read" )
452 On an IO::Async::Stream instance reading and writing a file descriptor
454 whose "fileno" is 4, which is a child of an
455 IO::Async::Protocol::Stream, will produce a line of output:
456 [Ia:Stream{rw=4}<-IaP:Stream] EVENT on_read
458 invoke_error
460 $notifier->invoke_error( $message, $name, @details )
461 Invokes the stored "on_error" event handler, passing in the given
463 arguments. If no handler is defined, it will be passed up to the
464 containing parent notifier, if one exists. If no parent exists, the
465 error message will be thrown as an exception by using die() and this
466 method will not return.
467 If a handler is found to handle this error, the method will return as
469 normal. However, as the expected use-case is to handle "fatal" errors
470 that now render the notifier unsuitable to continue, code should be
471 careful not to perform any further work after invoking it.
472 Specifically, sockets may become disconnected, or the entire notifier
473 may now be removed from its containing loop.
474 The $name and @details list should follow similar semantics to Future
476 failures. That is, the $name should be a string giving a category of
477 failure, and the @details list should contain additional arguments that
478 relate to that kind of failure.
479
481 Paul Evans <leonerd@leonerd.org.uk>
482perl v5.36.0 2023-01-20 IO::Async::Notifier(3)