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.2 by root, Thu Jul 2 15:13:03 2009 UTC vs.
Revision 1.9 by root, Sun Jul 12 16:33:26 2009 UTC

… …
7 use Async::Interrupt; 7 use Async::Interrupt;
8 8
9=head1 DESCRIPTION 9=head1 DESCRIPTION
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 while 89- that means you can also wait for the pipe to become readable (e.g. via
90L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
91and C<write> syscall.
43 92
44=over 4 93=over 4
45 94
46=cut 95=cut
47 96
48package Async::Interrupt; 97package Async::Interrupt;
49 98
50no warnings; 99no warnings;
51 100
52BEGIN { 101BEGIN {
53 $VERSION = '0.02'; 102 $VERSION = '0.041';
54 103
55 require XSLoader; 104 require XSLoader;
56 XSLoader::load Async::Interrupt::, $VERSION; 105 XSLoader::load Async::Interrupt::, $VERSION;
57} 106}
58 107
… …
99C<$value> is the C<value> passed to some earlier call to either C<$signal> 148C<$value> is the C<value> passed to some earlier call to either C<$signal>
100or the C<signal_func> function. 149or the C<signal_func> function.
101 150
102Note that, because the callback can be invoked at almost any time, you 151Note that, because the callback can be invoked at almost any time, you
103have to be careful at saving and restoring global variables that Perl 152have to be careful at saving and restoring global variables that Perl
104might use (the excetpion is C<errno>, which is aved and restored by 153might use (the exception is C<errno>, which is saved and restored by
105Async::Interrupt). The callback itself runs as part of the perl context, 154Async::Interrupt). The callback itself runs as part of the perl context,
106so 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
107which case the requireemnts set out for C<cb> apply as well). 156which case the requirements set out for C<cb> apply as well).
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.
108 166
109=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]
110 168
111Specifies two file descriptors (or file handles) that should be signalled 169Specifies two file descriptors (or file handles) that should be signalled
112whenever the async interrupt is signalled. This means a single octet will 170whenever the async interrupt is signalled. This means a single octet will
113be 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
114read 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
115are 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
116mode. 174mode.
117 175
118(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
119e.g. L<AnyEvent::Util> from the L<AnyEvent> distro). 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).
120 181
121The object will keep a reference to the file handles. 182The object will keep a reference to the file handles.
122 183
123This can be used to ensure that async notifications will interrupt event 184This can be used to ensure that async notifications will interrupt event
124frameworks as well. 185frameworks as well.
… …
128=cut 189=cut
129 190
130sub new { 191sub new {
131 my ($class, %arg) = @_; 192 my ($class, %arg) = @_;
132 193
133 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
134} 195}
135 196
136=item ($signal_func, $signal_arg) = $async->signal_func 197=item ($signal_func, $signal_arg) = $async->signal_func
137 198
138Returns the address of a function to call asynchronously. The function has 199Returns the address of a function to call asynchronously. The function has
… …
165C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is 226C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is
166portable). 227portable).
167 228
168=item $async->block 229=item $async->block
169 230
170Sometimes you need a "critical section" of code where
171
172=item $async->unblock 231=item $async->unblock
173 232
233Sometimes you need a "critical section" of code that will not be
234interrupted by an Async::Interrupt. This can be implemented by calling C<<
235$async->block >> before the critical section, and C<< $async->unblock >>
236afterwards.
237
238Note that there must be exactly one call of C<unblock> for every previous
239call to C<block> (i.e. calls can nest).
240
241Since ensuring this in the presence of exceptions and threads is
242usually more difficult than you imagine, I recommend using C<<
243$async->scoped_block >> instead.
244
245=item $async->scope_block
246
247This call C<< $async->block >> and installs a handler that is called when
248the current scope is exited (via an exception, by canceling the Coro
249thread, by calling last/goto etc.).
250
251This is the recommended (and fastest) way to implement critical sections.
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
174=cut 266=cut
175 267
1761; 2681;
177 269
178=back 270=back
179 271
180=head1 EXAMPLE 272=head1 EXAMPLE
181 273
182#TODO 274There really should be a complete C/XS example. Bug me about it. Better
275yet, create one.
183 276
184=head1 IMPLEMENTATION DETAILS AND LIMITATIONS 277=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
185 278
186This module works by "hijacking" SIGKILL, which is guarenteed to be always 279This module works by "hijacking" SIGKILL, which is guaranteed to always
187available in perl, but also cannot be caught, so is always available. 280exist, but also cannot be caught, so is always available.
188 281
189Basically, this module fakes the receive of a SIGKILL signal and 282Basically, this module fakes the occurance of a SIGKILL signal and
190then catches it. This makes normal signal handling slower (probably 283then intercepts the interpreter handling it. This makes normal signal
191unmeasurably), but has the advantage of not requiring a special runops nor 284handling slower (probably unmeasurably, though), but has the advantage
192slowing down normal perl execution a bit. 285of not requiring a special runops function, nor slowing down normal perl
286execution a bit.
193 287
194It 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
195modify (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
196C<int>, so we can assume that this is quite portbale, at least w.r.t. 290can assume that this is quite portable, at least w.r.t. signals).
197signals).
198 291
199=head1 AUTHOR 292=head1 AUTHOR
200 293
201 Marc Lehmann <schmorp@schmorp.de> 294 Marc Lehmann <schmorp@schmorp.de>
202 http://home.schmorp.de/ 295 http://home.schmorp.de/

Diff Legend

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