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.19 by root, Tue Jul 28 13:17:05 2009 UTC vs.
Revision 1.28 by root, Wed Nov 23 02:33:48 2011 UTC

… …
140=head2 Interrupt perl from another thread 140=head2 Interrupt perl from another thread
141 141
142This example interrupts the Perl interpreter from another thread, via the 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. 143XS API. This is used by e.g. the L<EV::Loop::Async> module.
144 144
145#TODO# 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.
223
146 224
147=head1 THE Async::Interrupt CLASS 225=head1 THE Async::Interrupt CLASS
148 226
149=over 4 227=over 4
150 228
… …
155use common::sense; 233use common::sense;
156 234
157BEGIN { 235BEGIN {
158 # the next line forces initialisation of internal 236 # the next line forces initialisation of internal
159 # signal handling variables, otherwise, PL_sig_pending 237 # signal handling variables, otherwise, PL_sig_pending
160 # etc. will be null pointers. 238 # etc. might be null pointers.
161 $SIG{KILL} = sub { }; 239 $SIG{KILL} = sub { };
162 240
163 our $VERSION = '1.0'; 241 our $VERSION = '1.05';
164 242
165 require XSLoader; 243 require XSLoader;
166 XSLoader::load ("Async::Interrupt", $VERSION); 244 XSLoader::load ("Async::Interrupt", $VERSION);
167} 245}
168 246
… …
354When you expect a lot of signals (e.g. when using SIGIO), then enabling 432When you expect a lot of signals (e.g. when using SIGIO), then enabling
355signal hysteresis can reduce the number of handler invocations 433signal hysteresis can reduce the number of handler invocations
356considerably, at the cost of two extra syscalls. 434considerably, at the cost of two extra syscalls.
357 435
358Note that setting the signal to C<SIG_IGN> can have unintended side 436Note that setting the signal to C<SIG_IGN> can have unintended side
359effects when you fork and exec other programs, as often they do nto expect 437effects when you fork and exec other programs, as often they do not expect
360signals to be ignored by default. 438signals to be ignored by default.
361 439
362=item $async->block 440=item $async->block
363 441
364=item $async->unblock 442=item $async->unblock
… …
458 536
459=back 537=back
460 538
461=head1 THE Async::Interrupt::EventPipe CLASS 539=head1 THE Async::Interrupt::EventPipe CLASS
462 540
463Pipes are the predominent utility to make asynchronous signals 541Pipes are the predominant utility to make asynchronous signals
464synchronous. 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
465broken 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
466an C<eventfd> instead. 544an C<eventfd> instead.
467 545
468This class creates selectable event pipes in a portable fashion: on 546This class creates selectable event pipes in a portable fashion: on
… …
498 576
499=item $epipe->drain 577=item $epipe->drain
500 578
501Drain (empty) the pipe. 579Drain (empty) the pipe.
502 580
581=item ($c_func, $c_arg) = $epipe->signal_func
582
583=item ($c_func, $c_arg) = $epipe->drain_func
584
585These two methods returns a function pointer and C<void *> argument
586that can be called to have the effect of C<< $epipe->signal >> or C<<
587$epipe->drain >>, respectively, on the XS level.
588
589They both have the following prototype and need to be passed their
590C<$c_arg>, which is a C<void *> cast to an C<IV>:
591
592 void (*c_func) (void *c_arg)
593
594An example call would look like:
595
596 c_func (c_arg);
597
503=item $epipe->renew 598=item $epipe->renew
504 599
505Recreates the pipe (useful after a fork). The reading side will not change 600Recreates the pipe (useful after a fork). The reading side will not change
506it's file descriptor number, but the writing side might. 601it's file descriptor number, but the writing side might.
507 602
603=item $epipe->wait
604
605This method blocks the process until there are events on the pipe. This is
606not a very event-based or ncie way of usign an event pipe, but it can be
607occasionally useful.
608
508=back 609=back
509 610
510=cut 611=cut
511 612
5121; 6131;
513
514=head1 EXAMPLE
515
516There really should be a complete C/XS example. Bug me about it. Better
517yet, create one.
518 614
519=head1 IMPLEMENTATION DETAILS AND LIMITATIONS 615=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
520 616
521This module works by "hijacking" SIGKILL, which is guaranteed to always 617This module works by "hijacking" SIGKILL, which is guaranteed to always
522exist, but also cannot be caught, so is always available. 618exist, but also cannot be caught, so is always available.

Diff Legend

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