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.26 by root, Wed Mar 31 00:47:11 2010 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
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
145On the Perl level, a new loop object (which contains the thread)
146is created, by first calling some XS constructor, querying the
147C-level callback function and feeding that as the C<c_cb> into the
148Async::Interrupt constructor:
149
150 my $self = XS_thread_constructor;
151 my ($c_func, $c_arg) = _c_func $self; # return the c callback
152 my $asy = new Async::Interrupt c_cb => [$c_func, $c_arg];
153
154Then the newly created Interrupt object is queried for the signaling
155function that the newly created thread should call, and this is in turn
156told to the thread object:
157
158 _attach $self, $asy->signal_func;
159
160So to repeat: first the XS object is created, then it is queried for the
161callback that should be called when the Interrupt object gets signalled.
162
163Then the interrupt object is queried for the callback fucntion that the
164thread should call to signal the Interrupt object, and this callback is
165then attached to the thread.
166
167You have to be careful that your new thread is not signalling before the
168signal function was configured, for example by starting the background
169thread only within C<_attach>.
170
171That concludes the Perl part.
172
173The XS part consists of the actual constructor which creates a thread,
174which is not relevant for this example, and two functions, C<_c_func>,
175which returns the Perl-side callback, and C<_attach>, which configures
176the signalling functioon that is safe toc all from another thread. For
177simplicity, we will use global variables to store the functions, normally
178you would somehow attach them to C<$self>.
179
180The C<c_func> simply returns the address of a static function and arranges
181for the object pointed to by C<$self> to be passed to it, as an integer:
182
183 void
184 _c_func (SV *loop)
185 PPCODE:
186 EXTEND (SP, 2);
187 PUSHs (sv_2mortal (newSViv (PTR2IV (c_func))));
188 PUSHs (sv_2mortal (newSViv (SvRV (loop))));
189
190This would be the callback (since it runs in a normal Perl context, it is
191permissible to manipulate Perl values):
192
193 static void
194 c_func (pTHX_ void *loop_, int value)
195 {
196 SV *loop_object = (SV *)loop_;
197 ...
198 }
199
200And this attaches the signalling callback:
201
202 static void (*my_sig_func) (void *signal_arg, int value);
203 static void *my_sig_arg;
204
205 void
206 _attach (SV *loop_, IV sig_func, void *sig_arg)
207 CODE:
208 {
209 my_sig_func = sig_func;
210 my_sig_arg = sig_arg;
211
212 /* now run the thread */
213 thread_create (&u->tid, l_run, 0);
214 }
215
216And C<l_run> (the background thread) would eventually call the signaling
217function:
218
219 my_sig_func (my_sig_arg, 0);
220
221You can have a look at L<EV::Loop::Async> for an actual example using
222intra-thread communication, locking and so on.
140 223
141 224
142=head1 THE Async::Interrupt CLASS 225=head1 THE Async::Interrupt CLASS
143 226
144=over 4 227=over 4
… …
149 232
150use common::sense; 233use common::sense;
151 234
152BEGIN { 235BEGIN {
153 # the next line forces initialisation of internal 236 # the next line forces initialisation of internal
154 # signal handling # variables 237 # signal handling variables, otherwise, PL_sig_pending
238 # etc. will be null pointers.
155 $SIG{KILL} = sub { }; 239 $SIG{KILL} = sub { };
156 240
157 our $VERSION = '0.6'; 241 our $VERSION = '1.04';
158 242
159 require XSLoader; 243 require XSLoader;
160 XSLoader::load ("Async::Interrupt", $VERSION); 244 XSLoader::load ("Async::Interrupt", $VERSION);
161} 245}
162 246
… …
185The exceptions are C<$!> and C<$@>, which are saved and restored by 269The exceptions are C<$!> and C<$@>, which are saved and restored by
186Async::Interrupt. 270Async::Interrupt.
187 271
188If the callback should throw an exception, then it will be caught, 272If the callback should throw an exception, then it will be caught,
189and C<$Async::Interrupt::DIED> will be called with C<$@> containing 273and C<$Async::Interrupt::DIED> will be called with C<$@> containing
190the exception. The default will simply C<warn> about the message and 274the exception. The default will simply C<warn> about the message and
191continue. 275continue.
192 276
193=item c_cb => [$c_func, $c_arg] 277=item c_cb => [$c_func, $c_arg]
194 278
195Registers a C callback the be invoked whenever the async interrupt is 279Registers a C callback the be invoked whenever the async interrupt is
… …
229the given signal is caught by the process. 313the given signal is caught by the process.
230 314
231Only one async can hook a given signal, and the signal will be restored to 315Only one async can hook a given signal, and the signal will be restored to
232defaults when the Async::Interrupt object gets destroyed. 316defaults when the Async::Interrupt object gets destroyed.
233 317
318=item signal_hysteresis => $boolean
319
320Sets the initial signal hysteresis state, see the C<signal_hysteresis>
321method, below.
322
234=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] 323=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
235 324
236Specifies two file descriptors (or file handles) that should be signalled 325Specifies two file descriptors (or file handles) that should be signalled
237whenever the async interrupt is signalled. This means a single octet will 326whenever 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 327be written to it, and before the callback is being invoked, it will be
… …
251 340
252If you want to share a single event pipe between multiple Async::Interrupt 341If you want to share a single event pipe between multiple Async::Interrupt
253objects, you can use the C<Async::Interrupt::EventPipe> class to manage 342objects, you can use the C<Async::Interrupt::EventPipe> class to manage
254those. 343those.
255 344
345=item pipe_autodrain => $boolean
346
347Sets the initial autodrain state, see the C<pipe_autodrain> method, below.
348
256=back 349=back
257 350
258=cut 351=cut
259 352
260sub new { 353sub new {
261 my ($class, %arg) = @_; 354 my ($class, %arg) = @_;
262 355
263 bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class 356 my $self = bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class;
357
358 # urgs, reminds me of Event
359 for my $attr (qw(pipe_autodrain signal_hysteresis)) {
360 $self->$attr ($arg{$attr}) if exists $arg{$attr};
361 }
362
363 $self
264} 364}
265 365
266=item ($signal_func, $signal_arg) = $async->signal_func 366=item ($signal_func, $signal_arg) = $async->signal_func
267 367
268Returns the address of a function to call asynchronously. The function 368Returns the address of a function to call asynchronously. The function
… …
436 536
437=back 537=back
438 538
439=head1 THE Async::Interrupt::EventPipe CLASS 539=head1 THE Async::Interrupt::EventPipe CLASS
440 540
441Pipes are the predominent utility to make asynchronous signals 541Pipes are the predominant utility to make asynchronous signals
442synchronous. However, pipes are hard to come by: they don't exist on the 542synchronous. However, pipes are hard to come by: they don't exist on the
443broken windows platform, and on GNU/Linux systems, you might want to use 543broken windows platform, and on GNU/Linux systems, you might want to use
444an C<eventfd> instead. 544an C<eventfd> instead.
445 545
446This class creates selectable event pipes in a portable fashion: on 546This class creates selectable event pipes in a portable fashion: on
… …
476 576
477=item $epipe->drain 577=item $epipe->drain
478 578
479Drain (empty) the pipe. 579Drain (empty) the pipe.
480 580
581=item ($c_func, $c_arg) = $epipe->drain_func
582
583Returns a function pointer and C<void *> argument that can be called to
584have the effect of C<< $epipe->drain >> on the XS level.
585
586It has the following prototype and needs to be passed the specified
587C<$c_arg>, which is a C<void *> cast to C<IV>:
588
589 void (*c_func) (void *c_arg)
590
591An example call would look like:
592
593 c_func (c_arg);
594
481=item $epipe->renew 595=item $epipe->renew
482 596
483Recreates the pipe (useful after a fork). The reading side will not change 597Recreates the pipe (useful after a fork). The reading side will not change
484it's file descriptor number, but the writing side might. 598it's file descriptor number, but the writing side might.
485 599
600=item $epipe->wait
601
602This method blocks the process until there are events on the pipe. This is
603not a very event-based or ncie way of usign an event pipe, but it can be
604occasionally useful.
605
486=back 606=back
487 607
488=cut 608=cut
489 609
4901; 6101;
491
492=head1 EXAMPLE
493
494There really should be a complete C/XS example. Bug me about it. Better
495yet, create one.
496 611
497=head1 IMPLEMENTATION DETAILS AND LIMITATIONS 612=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
498 613
499This module works by "hijacking" SIGKILL, which is guaranteed to always 614This module works by "hijacking" SIGKILL, which is guaranteed to always
500exist, but also cannot be caught, so is always available. 615exist, but also cannot be caught, so is always available.

Diff Legend

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