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