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.3 by root, Thu Jul 2 16:12:40 2009 UTC vs.
Revision 1.12 by root, Tue Jul 14 19:51:24 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
43#TODO# 90L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
91and C<write> syscall.
44 92
45=over 4 93=over 4
46 94
47=cut 95=cut
48 96
49package Async::Interrupt; 97package Async::Interrupt;
50 98
51no warnings; 99use common::sense;
52 100
53BEGIN { 101BEGIN {
102 # the next line forces initialisation of internal
103 # signal handling # variables
104 $SIG{KILL} = sub { };
105
54 $VERSION = '0.02'; 106 our $VERSION = '0.042';
55 107
56 require XSLoader; 108 require XSLoader;
57 XSLoader::load Async::Interrupt::, $VERSION; 109 XSLoader::load ("Async::Interrupt", $VERSION);
58} 110}
59 111
60our $DIED = sub { warn "$@" }; 112our $DIED = sub { warn "$@" };
61 113
62=item $async = new Async::Interrupt key => value... 114=item $async = new Async::Interrupt key => value...
… …
100C<$value> is the C<value> passed to some earlier call to either C<$signal> 152C<$value> is the C<value> passed to some earlier call to either C<$signal>
101or the C<signal_func> function. 153or the C<signal_func> function.
102 154
103Note that, because the callback can be invoked at almost any time, you 155Note that, because the callback can be invoked at almost any time, you
104have to be careful at saving and restoring global variables that Perl 156have to be careful at saving and restoring global variables that Perl
105might use (the excetpion is C<errno>, which is aved and restored by 157might use (the exception is C<errno>, which is saved and restored by
106Async::Interrupt). The callback itself runs as part of the perl context, 158Async::Interrupt). The callback itself runs as part of the perl context,
107so you can call any perl functions and modify any perl data structures (in 159so you can call any perl functions and modify any perl data structures (in
108which case the requireemnts set out for C<cb> apply as well). 160which case the requirements set out for C<cb> apply as well).
161
162=item signal => $signame_or_value
163
164When this parameter is specified, then the Async::Interrupt will hook the
165given signal, that is, it will effectively call C<< ->signal (0) >> each time
166the given signal is caught by the process.
167
168Only one async can hook a given signal, and the signal will be restored to
169defaults when the Async::Interrupt object gets destroyed.
109 170
110=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] 171=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
111 172
112Specifies two file descriptors (or file handles) that should be signalled 173Specifies two file descriptors (or file handles) that should be signalled
113whenever the async interrupt is signalled. This means a single octet will 174whenever the async interrupt is signalled. This means a single octet will
114be written to it, and before the callback is being invoked, it will be 175be written to it, and before the callback is being invoked, it will be
115read again. Due to races, it is unlikely but possible that multiple octets 176read again. Due to races, it is unlikely but possible that multiple octets
116are written. It is required that the file handles are both in nonblocking 177are written. It is required that the file handles are both in nonblocking
117mode. 178mode.
118 179
119(You can get a portable pipe and set non-blocking mode portably by using 180You can get a portable pipe and set non-blocking mode portably by using
120e.g. L<AnyEvent::Util> from the L<AnyEvent> distro). 181e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution.
182
183It is also possible to pass in a linux eventfd as both read and write
184handle (which is faster than a pipe).
121 185
122The object will keep a reference to the file handles. 186The object will keep a reference to the file handles.
123 187
124This can be used to ensure that async notifications will interrupt event 188This can be used to ensure that async notifications will interrupt event
125frameworks as well. 189frameworks as well.
… …
129=cut 193=cut
130 194
131sub new { 195sub new {
132 my ($class, %arg) = @_; 196 my ($class, %arg) = @_;
133 197
134 bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1]), $class 198 bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}), $class
135} 199}
136 200
137=item ($signal_func, $signal_arg) = $async->signal_func 201=item ($signal_func, $signal_arg) = $async->signal_func
138 202
139Returns the address of a function to call asynchronously. The function has 203Returns the address of a function to call asynchronously. The function has
… …
173Sometimes you need a "critical section" of code that will not be 237Sometimes you need a "critical section" of code that will not be
174interrupted by an Async::Interrupt. This can be implemented by calling C<< 238interrupted by an Async::Interrupt. This can be implemented by calling C<<
175$async->block >> before the critical section, and C<< $async->unblock >> 239$async->block >> before the critical section, and C<< $async->unblock >>
176afterwards. 240afterwards.
177 241
178Note that there must be exactly one call of C<unblock> for ever<y previous 242Note that there must be exactly one call of C<unblock> for every previous
179call to C<block> (i.e. calls can nest). 243call to C<block> (i.e. calls can nest).
180 244
181Since ensuring this in the presense of exceptions and threads is 245Since ensuring this in the presence of exceptions and threads is
182usually more difficult than you imagine, I recommend using C<< 246usually more difficult than you imagine, I recommend using C<<
183$async->scoped_block >> instead. 247$async->scoped_block >> instead.
184 248
185=item $async->scope_block 249=item $async->scope_block
186 250
… …
188the current scope is exited (via an exception, by canceling the Coro 252the current scope is exited (via an exception, by canceling the Coro
189thread, by calling last/goto etc.). 253thread, by calling last/goto etc.).
190 254
191This is the recommended (and fastest) way to implement critical sections. 255This is the recommended (and fastest) way to implement critical sections.
192 256
257=item $async->pipe_enable
258
259=item $async->pipe_disable
260
261Enable/disable signalling the pipe when the interrupt occurs (default is
262enabled). Writing to a pipe is relatively expensive, so it can be disabled
263when you know you are not waiting for it (for example, with L<EV> you
264could disable the pipe in a check watcher, and enable it in a prepare
265watcher).
266
267Note that when C<fd_disable> is in effect, no attempt to read from the
268pipe will be done.
269
193=cut 270=cut
194 271
1951; 2721;
196 273
197=back 274=back
198 275
199=head1 EXAMPLE 276=head1 EXAMPLE
200 277
201#TODO 278There really should be a complete C/XS example. Bug me about it. Better
279yet, create one.
202 280
203=head1 IMPLEMENTATION DETAILS AND LIMITATIONS 281=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
204 282
205This module works by "hijacking" SIGKILL, which is guarenteed to be always 283This module works by "hijacking" SIGKILL, which is guaranteed to always
206available in perl, but also cannot be caught, so is always available. 284exist, but also cannot be caught, so is always available.
207 285
208Basically, this module fakes the receive of a SIGKILL signal and 286Basically, this module fakes the occurance of a SIGKILL signal and
209then catches it. This makes normal signal handling slower (probably 287then intercepts the interpreter handling it. This makes normal signal
210unmeasurably), but has the advantage of not requiring a special runops nor 288handling slower (probably unmeasurably, though), but has the advantage
211slowing down normal perl execution a bit. 289of not requiring a special runops function, nor slowing down normal perl
290execution a bit.
212 291
213It assumes that C<sig_atomic_t> and C<int> are both exception-safe to 292It assumes that C<sig_atomic_t> and C<int> are both async-safe to modify
214modify (C<sig_atomic_> is used by this module, and perl itself uses 293(C<sig_atomic_> is used by this module, and perl itself uses C<int>, so we
215C<int>, so we can assume that this is quite portbale, at least w.r.t. 294can assume that this is quite portable, at least w.r.t. signals).
216signals).
217 295
218=head1 AUTHOR 296=head1 AUTHOR
219 297
220 Marc Lehmann <schmorp@schmorp.de> 298 Marc Lehmann <schmorp@schmorp.de>
221 http://home.schmorp.de/ 299 http://home.schmorp.de/

Diff Legend

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