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(
23 read_handle => \*STDIN,
24 on_read => sub {
25 my $self = shift;
26 my ( $buffref, $closed ) = @_;
27 $$buffref =~ s/^(.*)\n// or return 0;
28 print "You said $1\n";
29 return 1;
30 },
31 )
32 );
33 $notifier->add_child(
35 IO::Async::Signal->new(
36 name => 'INT',
37 on_receipt => sub {
38 print "Goodbye!\n";
39 $loop->loop_stop;
40 },
41 )
42 );
43 $loop->add( $notifier );
45 $loop->loop_forever;
47
49 This object class forms the basis for all the other event objects that
50 an "IO::Async" program uses. It provides the lowest level of
51 integration with a "IO::Async::Loop" container, and a facility to
52 collect Notifiers together, in a tree structure, where any Notifier can
53 contain a collection of children.
54 Normally, objects in this class would not be directly used by an end
56 program, as it performs no actual IO work, and generates no actual
57 events. These are all left to the various subclasses, such as:
58 · IO::Async::Handle - event callbacks for a non-blocking file
60 descriptor
61 · IO::Async::Stream - read and write buffers around an IO handle
63 · IO::Async::Sequencer - handle a serial pipeline of requests /
65 responses (EXPERIMENTAL)
66 · IO::Async::Timer - base class for Notifiers that use timed delays
68 · IO::Async::Signal - event callback on receipt of a POSIX signal
70 For more detail, see the SYNOPSIS section in one of the above.
72 One case where this object class would be used, is when a library
74 wishes to provide a sub-component which consists of multiple other
75 "Notifier" subclasses, such as "Handle"s and "Timers", but no
76 particular object is suitable to be the root of a tree. In this case, a
77 plain "Notifier" object can be used as the tree root, and all the other
78 notifiers added as children of it.
79
81 A specific subclass of "IO::Async::Notifier" defines named parameters
82 that control its behaviour. These may be passed to the "new"
83 constructor, or to the "configure" method. The documentation on each
84 specific subclass will give details on the parameters that exist, and
85 their uses. Some parameters may only support being set once at
86 construction time, or only support being changed if the object is in a
87 particular state.
88
90 $notifier = IO::Async::Notifier->new( %params )
91 This function returns a new instance of a "IO::Async::Notifier" object
92 with the given initial values of the named parameters.
93 Up until "IO::Async" version 0.19, this module used to implement the IO
95 handle features now found in the "IO::Async::Handle" subclass. To allow
96 for a smooth upgrade of existing code, this constructor check for any
97 %params key which looks like it belongs there instead. These keys are
98 "handle", "read_handle", "write_handle", "on_read_ready" and
99 "on_write_ready". If any of these keys are present, then a
100 "IO::Async::Handle" is returned.
101 Do not rely on this feature in new code. This logic exists purely to
103 provide an upgrade path from older code that still expects
104 "IO::Async::Notifier" to provide filehandle operations. This produces a
105 deprecation warning. At some point in the future this functionallity
106 may be removed.
107 $notifier->configure( %params )
109 Adjust the named parameters of the "Notifier" as given by the %params
110 hash.
111 $notifier->get_loop
113 Returns the "IO::Async::Loop" that this Notifier is a member of.
114
116 During the execution of a program, it may be the case that certain IO
117 handles cause other handles to be created; for example, new sockets
118 that have been "accept()"ed from a listening socket. To facilitate
119 these, a notifier may contain child notifier objects, that are
120 automatically added to or removed from the "IO::Async::Loop" that
121 manages their parent.
122 $parent = $notifier->parent()
124 Returns the parent of the notifier, or "undef" if does not have one.
125 @children = $notifier->children()
127 Returns a list of the child notifiers contained within this one.
128 $notifier->add_child( $child )
130 Adds a child notifier. This notifier will be added to the containing
131 loop, if the parent has one. Only a notifier that does not currently
132 have a parent and is not currently a member of any loop may be added as
133 a child. If the child itself has grandchildren, these will be
134 recursively added to the containing loop.
135 $notifier->remove_child( $child )
137 Removes a child notifier. The child will be removed from the containing
138 loop, if the parent has one. If the child itself has grandchildren,
139 these will be recurively removed from the loop.
140
142 "IO::Async::Notifier" is a base class provided so that specific
143 subclasses of it provide more specific behaviour. The base class
144 provides a number of methods that subclasses may wish to override.
145 If a subclass implements any of these, be sure to invoke the superclass
147 method at some point within the code.
148 $notifier->_init( $paramsref )
150 This method is called by the constructor just before calling
151 "configure()". It is passed a reference to the HASH storing the
152 constructor arguments.
153 This method may initialise internal details of the Notifier as
155 required, possibly by using parameters from the HASH. If any parameters
156 are construction-only they should be "delete"d from the hash.
157 $notifier->configure( %params )
159 This method is called by the constructor to set the initial values of
160 named parameters, and by users of the object to adjust the values once
161 constructed.
162 This method should "delete" from the %params hash any keys it has dealt
164 with, then pass the remaining ones to the "SUPER::configure()". The
165 base class implementation will throw an exception if there are any
166 unrecognised keys remaining.
167 $notifier->_add_to_loop( $loop )
169 This method is called when the Notifier has been added to a Loop;
170 either directly, or indirectly through being a child of a Notifer
171 already in a loop.
172 This method may be used to perform any initial startup activity
174 required for the Notifier to be fully functional but which requires a
175 Loop to do so.
176 $notifier->_remove_from_loop( $loop )
178 This method is called when the Notifier has been removed from a Loop;
179 either directly, or indirectly through being a child of a Notifier
180 removed from the loop.
181 This method may be used to undo the effects of any setup that the
183 "_add_to_loop" method had originally done.
184
186 $mref = $notifier->_capture_weakself( $code )
187 Returns a new CODE ref which, when invoked, will invoke the originally-
188 passed ref, with additionally a reference to the Notifier as its first
189 argument. The Notifier reference is stored weakly in $mref, so this
190 CODE ref may be stored in the Notifier itself without creating a cycle.
191 For example,
193 my $mref = $notifier->_capture_weakself( sub {
195 my ( $notifier, $arg ) = @_;
196 print "Notifier $notifier got argument $arg\n";
197 } );
198 $mref->( 123 );
200 This is provided as a utility for Notifier subclasses to use to build a
202 callback CODEref to pass to a Loop method, but which may also want to
203 store the CODE ref internally for efficiency.
204 The $code argument may also be a plain string, which will be used as a
206 method name; the returned CODE ref will then invoke that method on the
207 object.
208
210 Paul Evans <leonerd@leonerd.org.uk>
211perl v5.12.1 2010-06-09 IO::Async::Notifier(3)