1IO::Async::Notifier(3)User Contributed Perl DocumentationIO::Async::Notifier(3)
2
3
4

NAME

6       "IO::Async::Notifier" - base class for IO::Async event objects
7

SYNOPSIS

9       Usually not directly used by a program, but one valid use case may be:
10
11        use IO::Async::Notifier;
12
13        use IO::Async::Stream;
14        use IO::Async::Signal;
15
16        use IO::Async::Loop;
17        my $loop = IO::Async::Loop->new;
18
19        my $notifier = IO::Async::Notifier->new;
20
21        $notifier->add_child(
22           IO::Async::Stream->new_for_stdin(
23              on_read => sub {
24                 my $self = shift;
25                 my ( $buffref, $eof ) = @_;
26
27                 while( $$buffref =~ s/^(.*)\n// ) {
28                    print "You said $1\n";
29                 }
30
31                 return 0;
32              },
33           )
34        );
35
36        $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
46        $loop->add( $notifier );
47
48        $loop->run;
49

DESCRIPTION

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
57       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
61       ·   IO::Async::Handle - event callbacks for a non-blocking file
62           descriptor
63
64       ·   IO::Async::Stream - event callbacks and write bufering for a stream
65           filehandle
66
67       ·   IO::Async::Socket - event callbacks and send buffering for a socket
68           filehandle
69
70       ·   IO::Async::Timer - base class for Notifiers that use timed delays
71
72       ·   IO::Async::Signal - event callback on receipt of a POSIX signal
73
74       ·   IO::Async::PID - event callback on exit of a child process
75
76       ·   IO::Async::Process - start and manage a child process
77
78       For more detail, see the SYNOPSIS section in one of the above.
79
80       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

AS A MIXIN

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
95       The methods in this class all use only keys in the hash prefixed by
96       "IO_Async_Notifier__" for namespace purposes.
97
98       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
102        package SomeEventSource::Async;
103        use base qw( SomeEventSource IO::Async::Notifier );
104
105        sub _add_to_loop
106        {
107           my $self = shift;
108           my ( $loop ) = @_;
109
110           # Code here to set up event handling on $loop that may be required
111        }
112
113        sub _remove_from_loop
114        {
115           my $self = shift;
116           my ( $loop ) = @_;
117
118           # Code here to undo the event handling set up above
119        }
120
121       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

EVENTS

126       The following events are invoked, either using subclass methods or CODE
127       references in parameters:
128
129   on_error $message, $name, @details
130       Invoked by "invoke_error".
131

PARAMETERS

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
141       The following parameters are supported by all Notifiers:
142
143       on_error => CODE
144               CODE reference for event handler.
145
146       notifier_name => STRING
147               Optional string used to identify this particular Notifier. This
148               value will be returned by the "notifier_name" method.
149

CONSTRUCTOR

151   new
152          $notifier = IO::Async::Notifier->new( %params )
153
154       This function returns a new instance of a "IO::Async::Notifier" object
155       with the given initial values of the named parameters.
156
157       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

METHODS

164   configure
165          $notifier->configure( %params )
166
167       Adjust the named parameters of the "Notifier" as given by the %params
168       hash.
169
170   loop
171          $loop = $notifier->loop
172
173       Returns the IO::Async::Loop that this Notifier is a member of.
174
175   notifier_name
176          $name = $notifier->notifier_name
177
178       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
183   adopt_future
184          $f = $notifier->adopt_future( $f )
185
186       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
192       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
198        $notifier->adopt_future( $f->else_done() )
199
200       The future itself is returned.
201
202   adopted_futures
203          @f = $notifier->adopted_futures
204
205       Since version 0.73.
206
207       Returns a list of all the adopted and still-pending futures, in no
208       particular order.
209

CHILD NOTIFIERS

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
218   parent
219          $parent = $notifier->parent
220
221       Returns the parent of the notifier, or "undef" if does not have one.
222
223   children
224          @children = $notifier->children
225
226       Returns a list of the child notifiers contained within this one.
227
228   add_child
229          $notifier->add_child( $child )
230
231       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
237   remove_child
238          $notifier->remove_child( $child )
239
240       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
244   remove_from_parent
245          $notifier->remove_from_parent
246
247       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

SUBCLASS METHODS

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
257       If a subclass implements any of these, be sure to invoke the superclass
258       method at some point within the code.
259
260   _init
261          $notifier->_init( $paramsref )
262
263       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
267       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
271   configure
272          $notifier->configure( %params )
273
274       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
278       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
283   configure_unknown
284          $notifier->configure_unknown( %params )
285
286       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
293   _add_to_loop
294          $notifier->_add_to_loop( $loop )
295
296       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
300       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
304   _remove_from_loop
305          $notifier->_remove_from_loop( $loop )
306
307       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
311       This method may be used to undo the effects of any setup that the
312       "_add_to_loop" method had originally done.
313

UTILITY METHODS

315   _capture_weakself
316          $mref = $notifier->_capture_weakself( $code )
317
318       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
323       For example,
324
325        my $mref = $notifier->_capture_weakself( sub {
326           my ( $notifier, $arg ) = @_;
327           print "Notifier $notifier got argument $arg\n";
328        } );
329
330        $mref->( 123 );
331
332       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
336       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
343       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
349        $other_object->{on_event} = $notifier->_capture_weakself( sub {
350           my $notifier = shift or return;
351           my ( @event_args ) = @_;
352           ...
353        } );
354
355       For stand-alone generic implementation of this behaviour, see also
356       curry and "curry::weak".
357
358   _replace_weakself
359          $mref = $notifier->_replace_weakself( $code )
360
361       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
366       For example,
367
368        my $mref = $notifier->_replace_weakself( sub {
369           my ( $notifier, $arg ) = @_;
370           print "Notifier $notifier got argument $arg\n";
371        } );
372
373        $mref->( $object, 123 );
374
375       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
379       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
383       As with "_capture_weakself", care should be taken against Notifier
384       destruction if the $mref CODE reference is stored in some other object.
385
386   can_event
387          $code = $notifier->can_event( $event_name )
388
389       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
394   make_event_cb
395          $callback = $notifier->make_event_cb( $event_name )
396
397       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
401       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
407   maybe_make_event_cb
408          $callback = $notifier->maybe_make_event_cb( $event_name )
409
410       Similar to "make_event_cb" but will return "undef" if the object cannot
411       handle the named event, rather than throwing an exception.
412
413   invoke_event
414          @ret = $notifier->invoke_event( $event_name, @args )
415
416       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
421   maybe_invoke_event
422          $retref = $notifier->maybe_invoke_event( $event_name, @args )
423
424       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

DEBUGGING SUPPORT

431   debug_printf
432          $notifier->debug_printf( $format, @args )
433
434       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
443        IO::Async::Protocol::  =>  IaP:
444        IO::Async::            =>  Ia:
445        Net::Async::           =>  Na:
446
447       Finally, each notifier that has a name defined using the
448       "notifier_name" parameter has that name appended in braces.
449
450       For example, invoking
451
452        $stream->debug_printf( "EVENT on_read" )
453
454       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
458        [Ia:Stream{rw=4}<-IaP:Stream] EVENT on_read
459
460   invoke_error
461          $notifier->invoke_error( $message, $name, @details )
462
463       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
469       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
476       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

AUTHOR

482       Paul Evans <leonerd@leonerd.org.uk>
483
484
485
486perl v5.32.0                      2020-09-24            IO::Async::Notifier(3)
Impressum