ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/Async-Interrupt/Interrupt.pm
(Generate patch)

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.18 by root, Tue Jul 28 12:50:16 2009 UTC vs.
Revision 1.19 by root, Tue Jul 28 13:17:05 2009 UTC

… …
93L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read> 93L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
94and C<write> syscall. 94and C<write> syscall.
95 95
96=head1 USAGE EXAMPLES 96=head1 USAGE EXAMPLES
97 97
98=head2 Async::Interrupt to implement race-free signal handling 98=head2 Implementing race-free signal handling
99 99
100This example uses a single event pipe for all signals, and one 100This example uses a single event pipe for all signals, and one
101Async::Interrupt per signal. 101Async::Interrupt per signal. This code is actually what the L<AnyEvent>
102module uses itself when Async::Interrupt is available.
102 103
103First, create the event pipe and hook it into the event loop (this code is 104First, create the event pipe and hook it into the event loop
104actually what L<AnyEvent> uses itself):
105 105
106 $SIGPIPE = new Async::Interrupt::EventPipe; 106 $SIGPIPE = new Async::Interrupt::EventPipe;
107 $SIGPIPE_W = AnyEvent->io ( 107 $SIGPIPE_W = AnyEvent->io (
108 fh => $SIGPIPE->fileno, 108 fh => $SIGPIPE->fileno,
109 poll => "r", 109 poll => "r",
110 cb => \&_signal_check, 110 cb => \&_signal_check, # defined later
111 ); 111 );
112 112
113Then, for each signal to hook, create an Async::Interrupt object. The 113Then, for each signal to hook, create an Async::Interrupt object. The
114callback just sets a global variable, as we are only interested in 114callback just sets a global variable, as we are only interested in
115synchronous signals (i.e. when the event loop polls), which is why the 115synchronous signals (i.e. when the event loop polls), which is why the
116pipe draining is not done automatically. 116pipe draining is not done automatically.
117 117
118 my $interrupt = new Async::Interrupt 118 my $interrupt = new Async::Interrupt
119 cb => sub { undef $SIGNAL_RECEIVED{$signum} } 119 cb => sub { undef $SIGNAL_RECEIVED{$signum} }
120 signal => $signal, 120 signal => $signum,
121 pipe => [$SIGPIPE_R->filenos], 121 pipe => [$SIGPIPE->filenos],
122 pipe_autodrain => 0, 122 pipe_autodrain => 0,
123 ; 123 ;
124 124
125Finally, the I/O callback for the event pipe handles the signals: 125Finally, the I/O callback for the event pipe handles the signals:
126 126
… …
135 warn "signal $_ received\n"; 135 warn "signal $_ received\n";
136 } 136 }
137 } 137 }
138 } 138 }
139 139
140=head2 Interrupt perl from another thread
140 141
142This example interrupts the Perl interpreter from another thread, via the
143XS API. This is used by e.g. the L<EV::Loop::Async> module.
144
145#TODO#
141 146
142=head1 THE Async::Interrupt CLASS 147=head1 THE Async::Interrupt CLASS
143 148
144=over 4 149=over 4
145 150
… …
149 154
150use common::sense; 155use common::sense;
151 156
152BEGIN { 157BEGIN {
153 # the next line forces initialisation of internal 158 # the next line forces initialisation of internal
154 # signal handling # variables 159 # signal handling variables, otherwise, PL_sig_pending
160 # etc. will be null pointers.
155 $SIG{KILL} = sub { }; 161 $SIG{KILL} = sub { };
156 162
157 our $VERSION = '0.6'; 163 our $VERSION = '1.0';
158 164
159 require XSLoader; 165 require XSLoader;
160 XSLoader::load ("Async::Interrupt", $VERSION); 166 XSLoader::load ("Async::Interrupt", $VERSION);
161} 167}
162 168
… …
185The exceptions are C<$!> and C<$@>, which are saved and restored by 191The exceptions are C<$!> and C<$@>, which are saved and restored by
186Async::Interrupt. 192Async::Interrupt.
187 193
188If the callback should throw an exception, then it will be caught, 194If the callback should throw an exception, then it will be caught,
189and C<$Async::Interrupt::DIED> will be called with C<$@> containing 195and C<$Async::Interrupt::DIED> will be called with C<$@> containing
190the exception. The default will simply C<warn> about the message and 196the exception. The default will simply C<warn> about the message and
191continue. 197continue.
192 198
193=item c_cb => [$c_func, $c_arg] 199=item c_cb => [$c_func, $c_arg]
194 200
195Registers a C callback the be invoked whenever the async interrupt is 201Registers a C callback the be invoked whenever the async interrupt is
… …
229the given signal is caught by the process. 235the given signal is caught by the process.
230 236
231Only one async can hook a given signal, and the signal will be restored to 237Only one async can hook a given signal, and the signal will be restored to
232defaults when the Async::Interrupt object gets destroyed. 238defaults when the Async::Interrupt object gets destroyed.
233 239
240=item signal_hysteresis => $boolean
241
242Sets the initial signal hysteresis state, see the C<signal_hysteresis>
243method, below.
244
234=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] 245=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
235 246
236Specifies two file descriptors (or file handles) that should be signalled 247Specifies two file descriptors (or file handles) that should be signalled
237whenever the async interrupt is signalled. This means a single octet will 248whenever the async interrupt is signalled. This means a single octet will
238be written to it, and before the callback is being invoked, it will be 249be written to it, and before the callback is being invoked, it will be
… …
251 262
252If you want to share a single event pipe between multiple Async::Interrupt 263If you want to share a single event pipe between multiple Async::Interrupt
253objects, you can use the C<Async::Interrupt::EventPipe> class to manage 264objects, you can use the C<Async::Interrupt::EventPipe> class to manage
254those. 265those.
255 266
267=item pipe_autodrain => $boolean
268
269Sets the initial autodrain state, see the C<pipe_autodrain> method, below.
270
256=back 271=back
257 272
258=cut 273=cut
259 274
260sub new { 275sub new {
261 my ($class, %arg) = @_; 276 my ($class, %arg) = @_;
262 277
263 bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class 278 my $self = bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class;
279
280 # urgs, reminds me of Event
281 for my $attr (qw(pipe_autodrain signal_hysteresis)) {
282 $self->$attr ($arg{$attr}) if exists $arg{$attr};
283 }
284
285 $self
264} 286}
265 287
266=item ($signal_func, $signal_arg) = $async->signal_func 288=item ($signal_func, $signal_arg) = $async->signal_func
267 289
268Returns the address of a function to call asynchronously. The function 290Returns the address of a function to call asynchronously. The function

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines