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

Comparing Async-Interrupt/Interrupt.pm (file contents):
Revision 1.5 by root, Fri Jul 3 21:11:22 2009 UTC vs.
Revision 1.8 by root, Sun Jul 12 01:44:01 2009 UTC

… …
10 10
11This module implements a single feature only of interest to advanced perl 11This module implements a single feature only of interest to advanced perl
12modules, namely asynchronous interruptions (think "UNIX signals", which 12modules, namely asynchronous interruptions (think "UNIX signals", which
13are very similar). 13are very similar).
14 14
15Sometimes, modules wish to run code asynchronously (in another thread), 15Sometimes, modules wish to run code asynchronously (in another thread,
16and then signal the perl interpreter on certain events. One common way is 16or from a signal handler), and then signal the perl interpreter on
17to write some data to a pipe and use an event handling toolkit to watch 17certain events. One common way is to write some data to a pipe and use an
18for I/O events. Another way is to send a signal. Those methods are slow, 18event handling toolkit to watch for I/O events. Another way is to send
19and in the case of a pipe, also not asynchronous - it won't interrupt a 19a signal. Those methods are slow, and in the case of a pipe, also not
20running perl interpreter. 20asynchronous - it won't interrupt a running perl interpreter.
21 21
22This module implements asynchronous notifications that enable you to 22This module implements asynchronous notifications that enable you to
23signal running perl code form another thread, asynchronously, without 23signal running perl code from another thread, asynchronously, and
24issuing syscalls. 24sometimes even without using a single syscall.
25 25
26It works by creating an C<Async::Interrupt> object for each such use. This 26=head2 USAGE SCENARIOS
27object stores a perl and/or a C-level callback that is invoked when the 27
28C<Async::Interrupt> object gets signalled. It is executed at the next time 28=over 4
29the perl interpreter is running (i.e. it will interrupt a computation, but 29
30not an XS function or a syscall). 30=item Race-free signal handling
31
32There seems to be no way to do race-free signal handling in perl: to
33catch a signal, you have to execute Perl code, and between entering the
34interpreter C<select> function (or other blocking functions) and executing
35the select syscall is a small but relevant timespan during which signals
36will be queued, but perl signal handlers will not be executed and the
37blocking syscall will not be interrupted.
38
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
41completely.
42
43This can be used to implement the signal hadling in event loops,
44e.g. L<AnyEvent>, L<POE>, L<IO::Async::Loop> and so on.
45
46=item Background threads want speedy reporting
47
48Assume you want very exact timing, and you can spare an extra cpu core
49for that. Then you can run an extra thread that signals your perl
50interpreter. This means you can get a very exact timing source while your
51perl code is number crunching, without even using a syscall to communicate
52between your threads.
53
54For example the deliantra game server uses a variant of this technique
55to interrupt background processes regularly to send map updates to game
56clients.
57
58L<IO::AIO> and L<BDB> could also use this to speed up result reporting.
59
60=item Speedy event loop invocation
61
62One could use this module e.g. in L<Coro> to interrupt a running coro-thread
63and cause it to enter the event loop.
64
65Or one could bind to C<SIGIO> and tell some important sockets to send this
66signal, causing the event loop to be entered to reduce network latency.
67
68=back
69
70=head2 HOW TO USE
71
72You can use this module by creating an C<Async::Interrupt> object for each
73such event source. This object stores a perl and/or a C-level callback
74that is invoked when the C<Async::Interrupt> object gets signalled. It is
75executed at the next time the perl interpreter is running (i.e. it will
76interrupt a computation, but not an XS function or a syscall).
31 77
32You can signal the C<Async::Interrupt> object either by calling it's C<< 78You can signal the C<Async::Interrupt> object either by calling it's C<<
33->signal >> method, or, more commonly, by calling a C function. 79->signal >> method, or, more commonly, by calling a C function. There is
80also the built-in (POSIX) signal source.
34 81
35The C<< ->signal_func >> returns the address of the C function that is to 82The C<< ->signal_func >> returns the address of the C function that is to
36be called (plus an argument to be used during the call). The signalling 83be called (plus an argument to be used during the call). The signalling
37function also takes an integer argument in the range SIG_ATOMIC_MIN to 84function also takes an integer argument in the range SIG_ATOMIC_MIN to
38SIG_ATOMIC_MAX (guaranteed to allow at least 0..127). 85SIG_ATOMIC_MAX (guaranteed to allow at least 0..127).
39 86
40Since this kind of interruption is fast, but can only interrupt a 87Since this kind of interruption is fast, but can only interrupt a
41I<running> interpreter, there is optional support for also signalling a 88I<running> interpreter, there is optional support for signalling a pipe
42pipe - that means you can also wait for the pipe to become readable (e.g. 89- that means you can also wait for the pipe to become readable (e.g. via
43via L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a 90L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
44C<read> and C<write> syscall. 91and C<write> syscall.
45 92
46=over 4 93=over 4
47 94
48=cut 95=cut
49 96
50package Async::Interrupt; 97package Async::Interrupt;
51 98
52no warnings; 99no warnings;
53 100
54BEGIN { 101BEGIN {
55 $VERSION = '0.03'; 102 $VERSION = '0.04';
56 103
57 require XSLoader; 104 require XSLoader;
58 XSLoader::load Async::Interrupt::, $VERSION; 105 XSLoader::load Async::Interrupt::, $VERSION;
59} 106}
60 107
… …
106might use (the exception is C<errno>, which is saved and restored by 153might use (the exception is C<errno>, which is saved and restored by
107Async::Interrupt). The callback itself runs as part of the perl context, 154Async::Interrupt). The callback itself runs as part of the perl context,
108so you can call any perl functions and modify any perl data structures (in 155so you can call any perl functions and modify any perl data structures (in
109which case the requirements set out for C<cb> apply as well). 156which case the requirements set out for C<cb> apply as well).
110 157
158=item signal => $signame_or_value
159
160When this parameter is specified, then the Async::Interrupt will hook the
161given signal, that is, it will effectively call C<< ->signal (0) >> each time
162the given signal is caught by the process.
163
164Only one async can hook a given signal, and the signal will be restored to
165defaults when the Async::Interrupt object gets destroyed.
166
111=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] 167=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
112 168
113Specifies two file descriptors (or file handles) that should be signalled 169Specifies two file descriptors (or file handles) that should be signalled
114whenever the async interrupt is signalled. This means a single octet will 170whenever the async interrupt is signalled. This means a single octet will
115be written to it, and before the callback is being invoked, it will be 171be written to it, and before the callback is being invoked, it will be
116read again. Due to races, it is unlikely but possible that multiple octets 172read again. Due to races, it is unlikely but possible that multiple octets
117are written. It is required that the file handles are both in nonblocking 173are written. It is required that the file handles are both in nonblocking
118mode. 174mode.
119 175
120(You can get a portable pipe and set non-blocking mode portably by using 176You can get a portable pipe and set non-blocking mode portably by using
121e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution). 177e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution.
178
179It is also possible to pass in a linux eventfd as both read and write
180handle (which is faster than a pipe).
122 181
123The object will keep a reference to the file handles. 182The object will keep a reference to the file handles.
124 183
125This can be used to ensure that async notifications will interrupt event 184This can be used to ensure that async notifications will interrupt event
126frameworks as well. 185frameworks as well.
… …
130=cut 189=cut
131 190
132sub new { 191sub new {
133 my ($class, %arg) = @_; 192 my ($class, %arg) = @_;
134 193
135 bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1]), $class 194 bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}), $class
136} 195}
137 196
138=item ($signal_func, $signal_arg) = $async->signal_func 197=item ($signal_func, $signal_arg) = $async->signal_func
139 198
140Returns the address of a function to call asynchronously. The function has 199Returns the address of a function to call asynchronously. The function has
… …
189the current scope is exited (via an exception, by canceling the Coro 248the current scope is exited (via an exception, by canceling the Coro
190thread, by calling last/goto etc.). 249thread, by calling last/goto etc.).
191 250
192This is the recommended (and fastest) way to implement critical sections. 251This is the recommended (and fastest) way to implement critical sections.
193 252
253=item $async->pipe_enable
254
255=item $async->pipe_disable
256
257Enable/disable signalling the pipe when the interrupt occurs (default is
258enabled). Writing to a pipe is relatively expensive, so it can be disabled
259when you know you are not waiting for it (for example, with L<EV> you
260could disable the pipe in a check watcher, and enable it in a prepare
261watcher).
262
263Note that when C<fd_disable> is in effect, no attempt to read from the
264pipe will be done.
265
194=cut 266=cut
195 267
1961; 2681;
197 269
198=back 270=back
199 271
200=head1 EXAMPLE 272=head1 EXAMPLE
201 273
202There really should be a complete C/XS example. Bug me about it. 274There really should be a complete C/XS example. Bug me about it. Better
275yet, create one.
203 276
204=head1 IMPLEMENTATION DETAILS AND LIMITATIONS 277=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
205 278
206This module works by "hijacking" SIGKILL, which is guaranteed to be always 279This module works by "hijacking" SIGKILL, which is guaranteed to always
207available in perl, but also cannot be caught, so is always available. 280exist, but also cannot be caught, so is always available.
208 281
209Basically, this module fakes the receive of a SIGKILL signal and 282Basically, this module fakes the occurance of a SIGKILL signal and
210then catches it. This makes normal signal handling slower (probably 283then intercepts the interpreter handling it. This makes normal signal
211unmeasurably), but has the advantage of not requiring a special runops nor 284handling slower (probably unmeasurably, though), but has the advantage
212slowing down normal perl execution a bit. 285of not requiring a special runops function, nor slowing down normal perl
286execution a bit.
213 287
214It assumes that C<sig_atomic_t> and C<int> are both exception-safe to 288It assumes that C<sig_atomic_t> and C<int> are both async-safe to modify
215modify (C<sig_atomic_> is used by this module, and perl itself uses 289(C<sig_atomic_> is used by this module, and perl itself uses C<int>, so we
216C<int>, so we can assume that this is quite portable, at least w.r.t. 290can assume that this is quite portable, at least w.r.t. signals).
217signals).
218 291
219=head1 AUTHOR 292=head1 AUTHOR
220 293
221 Marc Lehmann <schmorp@schmorp.de> 294 Marc Lehmann <schmorp@schmorp.de>
222 http://home.schmorp.de/ 295 http://home.schmorp.de/

Diff Legend

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