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.39 by root, Thu Jul 18 09:13:00 2019 UTC

… …
38 38
39You can use this module to bind a signal to a callback while at the same 39You can use this module to bind a signal to a callback while at the same
40time activating an event pipe that you can C<select> on, fixing the race 40time activating an event pipe that you can C<select> on, fixing the race
41completely. 41completely.
42 42
43This can be used to implement the signal hadling in event loops, 43This can be used to implement the signal handling in event loops,
44e.g. L<AnyEvent>, L<POE>, L<IO::Async::Loop> and so on. 44e.g. L<AnyEvent>, L<POE>, L<IO::Async::Loop> and so on.
45 45
46=item Background threads want speedy reporting 46=item Background threads want speedy reporting
47 47
48Assume you want very exact timing, and you can spare an extra cpu core 48Assume you want very exact timing, and you can spare an extra cpu core
… …
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 => $signum, 120 signal => $signum,
121 pipe => [$SIGPIPE->filenos], 121 pipe => [$SIGPIPE->filenos],
122 pipe_autodrain => 0, 122 pipe_autodrain => 0,
123 ; 123 ;
124 124
… …
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 function 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.25;
164 242
165 require XSLoader; 243 require XSLoader;
166 XSLoader::load ("Async::Interrupt", $VERSION); 244 XSLoader::load ("Async::Interrupt", $VERSION);
167} 245}
168 246
… …
341might imply, do anything with POSIX signals). 419might imply, do anything with POSIX signals).
342 420
343C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0> 421C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
344(1..127 is portable). 422(1..127 is portable).
345 423
424=item $async->handle
425
426Calls the callback if the object is pending.
427
428This method does not need to be called normally, as it will be invoked
429automatically. However, it can be used to force handling of outstanding
430interrupts while the object is blocked.
431
432One reason why one might want to do that is when you want to switch
433from asynchronous interruptions to synchronous one, using e.g. an event
434loop. To do that, one would first C<< $async->block >> the interrupt
435object, then register a read watcher on the C<pipe_fileno> that calls C<<
436$async->handle >>.
437
438This disables asynchronous interruptions, but ensures that interrupts are
439handled by the event loop.
440
346=item $async->signal_hysteresis ($enable) 441=item $async->signal_hysteresis ($enable)
347 442
348Enables or disables signal hysteresis (default: disabled). If a POSIX 443Enables or disables signal hysteresis (default: disabled). If a POSIX
349signal is used as a signal source for the interrupt object, then enabling 444signal is used as a signal source for the interrupt object, then enabling
350signal hysteresis causes Async::Interrupt to reset the signal action to 445signal hysteresis causes Async::Interrupt to reset the signal action to
… …
354When you expect a lot of signals (e.g. when using SIGIO), then enabling 449When you expect a lot of signals (e.g. when using SIGIO), then enabling
355signal hysteresis can reduce the number of handler invocations 450signal hysteresis can reduce the number of handler invocations
356considerably, at the cost of two extra syscalls. 451considerably, at the cost of two extra syscalls.
357 452
358Note that setting the signal to C<SIG_IGN> can have unintended side 453Note 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 454effects when you fork and exec other programs, as often they do not expect
360signals to be ignored by default. 455signals to be ignored by default.
361 456
362=item $async->block 457=item $async->block
363 458
364=item $async->unblock 459=item $async->unblock
… …
417=item $fileno = $async->pipe_fileno 512=item $fileno = $async->pipe_fileno
418 513
419Returns the reading side of the signalling pipe. If no signalling pipe is 514Returns the reading side of the signalling pipe. If no signalling pipe is
420currently attached to the object, it will dynamically create one. 515currently attached to the object, it will dynamically create one.
421 516
422Note that the only valid oepration on this file descriptor is to wait 517Note that the only valid operation on this file descriptor is to wait
423until it is readable. The fd might belong currently to a pipe, a tcp 518until it is readable. The fd might belong currently to a pipe, a tcp
424socket, or an eventfd, depending on the platform, and is guaranteed to be 519socket, or an eventfd, depending on the platform, and is guaranteed to be
425C<select>able. 520C<select>able.
426 521
427=item $async->pipe_autodrain ($enable) 522=item $async->pipe_autodrain ($enable)
… …
432draining. 527draining.
433 528
434This is useful when you want to share one pipe among many Async::Interrupt 529This is useful when you want to share one pipe among many Async::Interrupt
435objects. 530objects.
436 531
532=item $async->pipe_drain
533
534Drains the pipe manually, for example, when autodrain is disabled. Does
535nothing when no pipe is enabled.
536
437=item $async->post_fork 537=item $async->post_fork
438 538
439The object will not normally be usable after a fork (as the pipe fd is 539The object will not normally be usable after a fork (as the pipe fd is
440shared between processes). Calling this method after a fork in the child 540shared between processes). Calling this method after a fork in the child
441ensures that the object will work as expected again. It only needs to be 541ensures that the object will work as expected again. It only needs to be
… …
458 558
459=back 559=back
460 560
461=head1 THE Async::Interrupt::EventPipe CLASS 561=head1 THE Async::Interrupt::EventPipe CLASS
462 562
463Pipes are the predominent utility to make asynchronous signals 563Pipes are the predominant utility to make asynchronous signals
464synchronous. However, pipes are hard to come by: they don't exist on the 564synchronous. 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 565broken windows platform, and on GNU/Linux systems, you might want to use
466an C<eventfd> instead. 566an C<eventfd> instead.
467 567
468This class creates selectable event pipes in a portable fashion: on 568This class creates selectable event pipes in a portable fashion: on
… …
498 598
499=item $epipe->drain 599=item $epipe->drain
500 600
501Drain (empty) the pipe. 601Drain (empty) the pipe.
502 602
603=item ($c_func, $c_arg) = $epipe->signal_func
604
605=item ($c_func, $c_arg) = $epipe->drain_func
606
607These two methods returns a function pointer and C<void *> argument
608that can be called to have the effect of C<< $epipe->signal >> or C<<
609$epipe->drain >>, respectively, on the XS level.
610
611They both have the following prototype and need to be passed their
612C<$c_arg>, which is a C<void *> cast to an C<IV>:
613
614 void (*c_func) (void *c_arg)
615
616An example call would look like:
617
618 c_func (c_arg);
619
503=item $epipe->renew 620=item $epipe->renew
504 621
505Recreates the pipe (useful after a fork). The reading side will not change 622Recreates the pipe (usually required in the child after a fork). The
506it's file descriptor number, but the writing side might. 623reading side will not change it's file descriptor number, but the writing
624side might.
625
626=item $epipe->wait
627
628This method blocks the process until there are events on the pipe. This is
629not a very event-based or ncie way of usign an event pipe, but it can be
630occasionally useful.
507 631
508=back 632=back
509 633
510=cut 634=cut
511 635
5121; 6361;
513
514=head1 EXAMPLE
515
516There really should be a complete C/XS example. Bug me about it. Better
517yet, create one.
518 637
519=head1 IMPLEMENTATION DETAILS AND LIMITATIONS 638=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
520 639
521This module works by "hijacking" SIGKILL, which is guaranteed to always 640This module works by "hijacking" SIGKILL, which is guaranteed to always
522exist, but also cannot be caught, so is always available. 641exist, but also cannot be caught, so is always available.
523 642
524Basically, this module fakes the occurance of a SIGKILL signal and 643Basically, this module fakes the occurence of a SIGKILL signal and
525then intercepts the interpreter handling it. This makes normal signal 644then intercepts the interpreter handling it. This makes normal signal
526handling slower (probably unmeasurably, though), but has the advantage 645handling slower (probably unmeasurably, though), but has the advantage
527of not requiring a special runops function, nor slowing down normal perl 646of not requiring a special runops function, nor slowing down normal perl
528execution a bit. 647execution a bit.
529 648

Diff Legend

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