… | |
… | |
7 | use Async::Interrupt; |
7 | use Async::Interrupt; |
8 | |
8 | |
9 | =head1 DESCRIPTION |
9 | =head1 DESCRIPTION |
10 | |
10 | |
11 | This module implements a single feature only of interest to advanced perl |
11 | This module implements a single feature only of interest to advanced perl |
12 | modules, namely asynchronous interruptions (think "unix signals", which |
12 | modules, namely asynchronous interruptions (think "UNIX signals", which |
13 | are very similar). |
13 | are very similar). |
14 | |
14 | |
15 | Sometimes, modules wish to run code asynchronously (in another thread), |
15 | Sometimes, modules wish to run code asynchronously (in another thread, |
16 | and then signal the perl interpreter on certain events. One common way is |
16 | or from a signal handler), and then signal the perl interpreter on |
17 | to write some data to a pipe and use an event handling toolkit to watch |
17 | certain events. One common way is to write some data to a pipe and use an |
18 | for I/O events. Another way is to send a signal. Those methods are slow, |
18 | event handling toolkit to watch for I/O events. Another way is to send |
19 | and in the case of a pipe, also not asynchronous - it won't interrupt a |
19 | a signal. Those methods are slow, and in the case of a pipe, also not |
20 | running perl interpreter. |
20 | asynchronous - it won't interrupt a running perl interpreter. |
21 | |
21 | |
22 | This module implements asynchronous notifications that enable you to |
22 | This module implements asynchronous notifications that enable you to |
23 | signal running perl code form another thread, asynchronously, without |
23 | signal running perl code from another thread, asynchronously, and |
24 | issuing syscalls. |
24 | sometimes even without using a single syscall. |
25 | |
25 | |
26 | It works by creating an C<Async::Interrupt> object for each such use. This |
26 | =head2 USAGE SCENARIOS |
27 | object stores a perl and/or a C-level callback that is invoked when the |
27 | |
28 | C<Async::Interrupt> object gets signalled. It is executed at the next time |
28 | =over 4 |
29 | the perl interpreter is running (i.e. it will interrupt a computation, but |
29 | |
30 | not an XS function or a syscall). |
30 | =item Race-free signal handling |
|
|
31 | |
|
|
32 | There seems to be no way to do race-free signal handling in perl: to |
|
|
33 | catch a signal, you have to execute Perl code, and between entering the |
|
|
34 | interpreter C<select> function (or other blocking functions) and executing |
|
|
35 | the select syscall is a small but relevant timespan during which signals |
|
|
36 | will be queued, but perl signal handlers will not be executed and the |
|
|
37 | blocking syscall will not be interrupted. |
|
|
38 | |
|
|
39 | You can use this module to bind a signal to a callback while at the same |
|
|
40 | time activating an event pipe that you can C<select> on, fixing the race |
|
|
41 | completely. |
|
|
42 | |
|
|
43 | This can be used to implement the signal hadling in event loops, |
|
|
44 | e.g. L<AnyEvent>, L<POE>, L<IO::Async::Loop> and so on. |
|
|
45 | |
|
|
46 | =item Background threads want speedy reporting |
|
|
47 | |
|
|
48 | Assume you want very exact timing, and you can spare an extra cpu core |
|
|
49 | for that. Then you can run an extra thread that signals your perl |
|
|
50 | interpreter. This means you can get a very exact timing source while your |
|
|
51 | perl code is number crunching, without even using a syscall to communicate |
|
|
52 | between your threads. |
|
|
53 | |
|
|
54 | For example the deliantra game server uses a variant of this technique |
|
|
55 | to interrupt background processes regularly to send map updates to game |
|
|
56 | clients. |
|
|
57 | |
|
|
58 | L<IO::AIO> and L<BDB> could also use this to speed up result reporting. |
|
|
59 | |
|
|
60 | =item Speedy event loop invocation |
|
|
61 | |
|
|
62 | One could use this module e.g. in L<Coro> to interrupt a running coro-thread |
|
|
63 | and cause it to enter the event loop. |
|
|
64 | |
|
|
65 | Or one could bind to C<SIGIO> and tell some important sockets to send this |
|
|
66 | signal, causing the event loop to be entered to reduce network latency. |
|
|
67 | |
|
|
68 | =back |
|
|
69 | |
|
|
70 | =head2 HOW TO USE |
|
|
71 | |
|
|
72 | You can use this module by creating an C<Async::Interrupt> object for each |
|
|
73 | such event source. This object stores a perl and/or a C-level callback |
|
|
74 | that is invoked when the C<Async::Interrupt> object gets signalled. It is |
|
|
75 | executed at the next time the perl interpreter is running (i.e. it will |
|
|
76 | interrupt a computation, but not an XS function or a syscall). |
31 | |
77 | |
32 | You can signal the C<Async::Interrupt> object either by calling it's C<< |
78 | You 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 |
|
|
80 | also the built-in (POSIX) signal source. |
34 | |
81 | |
35 | The C<< ->signal_func >> returns the address of the C function that is to |
82 | The C<< ->signal_func >> returns the address of the C function that is to |
36 | be called (plus an argument to be used during the call). The signalling |
83 | be called (plus an argument to be used during the call). The signalling |
37 | function also takes an integer argument in the range SIG_ATOMIC_MIN to |
84 | function also takes an integer argument in the range SIG_ATOMIC_MIN to |
38 | SIG_ATOMIC_MAX (guaranteed to allow at least 0..127). |
85 | SIG_ATOMIC_MAX (guaranteed to allow at least 0..127). |
39 | |
86 | |
40 | Since this kind of interruption is fast, but can only interrupt a |
87 | Since this kind of interruption is fast, but can only interrupt a |
41 | I<running> interpreter, there is optional support for also signalling a |
88 | I<running> interpreter, there is optional support for signalling a pipe |
42 | pipe - 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 |
|
|
90 | L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read> |
|
|
91 | and C<write> syscall. |
43 | |
92 | |
44 | =over 4 |
93 | =over 4 |
45 | |
94 | |
46 | =cut |
95 | =cut |
47 | |
96 | |
48 | package Async::Interrupt; |
97 | package Async::Interrupt; |
49 | |
98 | |
50 | no warnings; |
99 | use common::sense; |
51 | |
100 | |
52 | BEGIN { |
101 | BEGIN { |
|
|
102 | # the next line forces initialisation of internal |
|
|
103 | # signal handling # variables |
|
|
104 | $SIG{KILL} = sub { }; |
|
|
105 | |
53 | $VERSION = '0.02'; |
106 | our $VERSION = '0.501'; |
54 | |
107 | |
55 | require XSLoader; |
108 | require XSLoader; |
56 | XSLoader::load Async::Interrupt::, $VERSION; |
109 | XSLoader::load ("Async::Interrupt", $VERSION); |
57 | } |
110 | } |
58 | |
111 | |
59 | our $DIED = sub { warn "$@" }; |
112 | our $DIED = sub { warn "$@" }; |
60 | |
113 | |
61 | =item $async = new Async::Interrupt key => value... |
114 | =item $async = new Async::Interrupt key => value... |
… | |
… | |
99 | C<$value> is the C<value> passed to some earlier call to either C<$signal> |
152 | C<$value> is the C<value> passed to some earlier call to either C<$signal> |
100 | or the C<signal_func> function. |
153 | or the C<signal_func> function. |
101 | |
154 | |
102 | Note that, because the callback can be invoked at almost any time, you |
155 | Note that, because the callback can be invoked at almost any time, you |
103 | have to be careful at saving and restoring global variables that Perl |
156 | have to be careful at saving and restoring global variables that Perl |
104 | might use (the excetpion is C<errno>, which is aved and restored by |
157 | might use (the exception is C<errno>, which is saved and restored by |
105 | Async::Interrupt). The callback itself runs as part of the perl context, |
158 | Async::Interrupt). The callback itself runs as part of the perl context, |
106 | so you can call any perl functions and modify any perl data structures (in |
159 | so you can call any perl functions and modify any perl data structures (in |
107 | which case the requireemnts set out for C<cb> apply as well). |
160 | which case the requirements set out for C<cb> apply as well). |
|
|
161 | |
|
|
162 | =item var => $scalar_ref |
|
|
163 | |
|
|
164 | When specified, then the given argument must be a reference to a |
|
|
165 | scalar. The scalar will be set to C<0> intiially. Signalling the interrupt |
|
|
166 | object will set it to the passed value, handling the interrupt will reset |
|
|
167 | it to C<0> again. |
|
|
168 | |
|
|
169 | Note that the only thing you are legally allowed to do is to is to check |
|
|
170 | the variable in a boolean or integer context (e.g. comparing it with a |
|
|
171 | string, or printing it, will I<destroy> it and might cause your program to |
|
|
172 | crash or worse). |
|
|
173 | |
|
|
174 | =item signal => $signame_or_value |
|
|
175 | |
|
|
176 | When this parameter is specified, then the Async::Interrupt will hook the |
|
|
177 | given signal, that is, it will effectively call C<< ->signal (0) >> each time |
|
|
178 | the given signal is caught by the process. |
|
|
179 | |
|
|
180 | Only one async can hook a given signal, and the signal will be restored to |
|
|
181 | defaults when the Async::Interrupt object gets destroyed. |
108 | |
182 | |
109 | =item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] |
183 | =item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] |
110 | |
184 | |
111 | Specifies two file descriptors (or file handles) that should be signalled |
185 | Specifies two file descriptors (or file handles) that should be signalled |
112 | whenever the async interrupt is signalled. This means a single octet will |
186 | whenever the async interrupt is signalled. This means a single octet will |
113 | be written to it, and before the callback is being invoked, it will be |
187 | be written to it, and before the callback is being invoked, it will be |
114 | read again. Due to races, it is unlikely but possible that multiple octets |
188 | read again. Due to races, it is unlikely but possible that multiple octets |
115 | are written. It is required that the file handles are both in nonblocking |
189 | are written. It is required that the file handles are both in nonblocking |
116 | mode. |
190 | mode. |
117 | |
191 | |
118 | (You can get a portable pipe and set non-blocking mode portably by using |
|
|
119 | e.g. L<AnyEvent::Util> from the L<AnyEvent> distro). |
|
|
120 | |
|
|
121 | The object will keep a reference to the file handles. |
192 | The object will keep a reference to the file handles. |
122 | |
193 | |
123 | This can be used to ensure that async notifications will interrupt event |
194 | This can be used to ensure that async notifications will interrupt event |
124 | frameworks as well. |
195 | frameworks as well. |
125 | |
196 | |
|
|
197 | Note that C<Async::Interrupt> will create a suitable signal fd |
|
|
198 | automatically when your program requests one, so you don't have to specify |
|
|
199 | this agrument when all you want is an extra file descriptor to watch. |
|
|
200 | |
126 | =back |
201 | =back |
127 | |
202 | |
128 | =cut |
203 | =cut |
129 | |
204 | |
130 | sub new { |
205 | sub new { |
131 | my ($class, %arg) = @_; |
206 | my ($class, %arg) = @_; |
132 | |
207 | |
133 | bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1]), $class |
208 | bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class |
134 | } |
209 | } |
135 | |
210 | |
136 | =item ($signal_func, $signal_arg) = $async->signal_func |
211 | =item ($signal_func, $signal_arg) = $async->signal_func |
137 | |
212 | |
138 | Returns the address of a function to call asynchronously. The function has |
213 | Returns the address of a function to call asynchronously. The function has |
… | |
… | |
146 | signal_func (signal_arg, 0); |
221 | signal_func (signal_arg, 0); |
147 | |
222 | |
148 | The function is safe to call from within signal and thread contexts, at |
223 | The function is safe to call from within signal and thread contexts, at |
149 | any time. The specified C<value> is passed to both C and Perl callback. |
224 | any time. The specified C<value> is passed to both C and Perl callback. |
150 | |
225 | |
151 | C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is |
226 | C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0> |
152 | portable). |
227 | (1..127 is portable). |
153 | |
228 | |
154 | If the function is called while the Async::Interrupt object is already |
229 | If the function is called while the Async::Interrupt object is already |
155 | signaled but before the callbacks are being executed, then the stored |
230 | signaled but before the callbacks are being executed, then the stored |
156 | C<value> is either the old or the new one. Due to the asynchronous |
231 | C<value> is either the old or the new one. Due to the asynchronous |
157 | nature of the code, the C<value> can even be passed to two consecutive |
232 | nature of the code, the C<value> can even be passed to two consecutive |
158 | invocations of the callback. |
233 | invocations of the callback. |
159 | |
234 | |
|
|
235 | =item $address = $async->c_var |
|
|
236 | |
|
|
237 | Returns the address (cast to IV) of an C<IV> variable. The variable is set |
|
|
238 | to C<0> initially and gets set to the passed value whenever the object |
|
|
239 | gets signalled, and reset to C<0> once the interrupt has been handled. |
|
|
240 | |
|
|
241 | Note that it is often beneficial to just call C<PERL_ASYNC_CHECK ()> to |
|
|
242 | handle any interrupts. |
|
|
243 | |
|
|
244 | Example: call some XS function to store the address, then show C code |
|
|
245 | waiting for it. |
|
|
246 | |
|
|
247 | my_xs_func $async->c_var; |
|
|
248 | |
|
|
249 | static IV *valuep; |
|
|
250 | |
|
|
251 | void |
|
|
252 | my_xs_func (void *addr) |
|
|
253 | CODE: |
|
|
254 | valuep = (IV *)addr; |
|
|
255 | |
|
|
256 | // code in a loop, waiting |
|
|
257 | while (!*valuep) |
|
|
258 | ; // do soemthing |
|
|
259 | |
160 | =item $async->signal ($value=0) |
260 | =item $async->signal ($value=1) |
161 | |
261 | |
162 | This signals the given async object from Perl code. Semi-obviously, this |
262 | This signals the given async object from Perl code. Semi-obviously, this |
163 | will instantly trigger the callback invocation. |
263 | will instantly trigger the callback invocation. |
164 | |
264 | |
165 | C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is |
265 | C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0> |
166 | portable). |
266 | (1..127 is portable). |
167 | |
267 | |
168 | =item $async->block |
268 | =item $async->block |
169 | |
269 | |
170 | Sometimes you need a "critical section" of code where |
|
|
171 | |
|
|
172 | =item $async->unblock |
270 | =item $async->unblock |
173 | |
271 | |
|
|
272 | Sometimes you need a "critical section" of code that will not be |
|
|
273 | interrupted by an Async::Interrupt. This can be implemented by calling C<< |
|
|
274 | $async->block >> before the critical section, and C<< $async->unblock >> |
|
|
275 | afterwards. |
|
|
276 | |
|
|
277 | Note that there must be exactly one call of C<unblock> for every previous |
|
|
278 | call to C<block> (i.e. calls can nest). |
|
|
279 | |
|
|
280 | Since ensuring this in the presence of exceptions and threads is |
|
|
281 | usually more difficult than you imagine, I recommend using C<< |
|
|
282 | $async->scoped_block >> instead. |
|
|
283 | |
|
|
284 | =item $async->scope_block |
|
|
285 | |
|
|
286 | This call C<< $async->block >> and installs a handler that is called when |
|
|
287 | the current scope is exited (via an exception, by canceling the Coro |
|
|
288 | thread, by calling last/goto etc.). |
|
|
289 | |
|
|
290 | This is the recommended (and fastest) way to implement critical sections. |
|
|
291 | |
|
|
292 | =item $async->pipe_enable |
|
|
293 | |
|
|
294 | =item $async->pipe_disable |
|
|
295 | |
|
|
296 | Enable/disable signalling the pipe when the interrupt occurs (default is |
|
|
297 | enabled). Writing to a pipe is relatively expensive, so it can be disabled |
|
|
298 | when you know you are not waiting for it (for example, with L<EV> you |
|
|
299 | could disable the pipe in a check watcher, and enable it in a prepare |
|
|
300 | watcher). |
|
|
301 | |
|
|
302 | Note that currently, while C<pipe_disable> is in effect, no attempt to |
|
|
303 | read from the pipe will be done when handling events. This might change as |
|
|
304 | soon as I realize why this is a mistake. |
|
|
305 | |
|
|
306 | =item $fileno = $async->pipe_fileno |
|
|
307 | |
|
|
308 | Returns the reading side of the signalling pipe. If no signalling pipe is |
|
|
309 | currently attached to the object, it will dynamically create one. |
|
|
310 | |
|
|
311 | Note that the only valid oepration on this file descriptor is to wait |
|
|
312 | until it is readable. The fd might belong currently to a pipe, a tcp |
|
|
313 | socket, or an eventfd, depending on the platform, and is guaranteed to be |
|
|
314 | C<select>able. |
|
|
315 | |
|
|
316 | =item $async->post_fork |
|
|
317 | |
|
|
318 | The object will not normally be usable after a fork (as the pipe fd is |
|
|
319 | shared between processes). Calling this method after a fork in the child |
|
|
320 | ensures that the object will work as expected again. It only needs to be |
|
|
321 | called when the async object is used in the child. |
|
|
322 | |
|
|
323 | This only works when the pipe was created by Async::Interrupt. |
|
|
324 | |
|
|
325 | Async::Interrupt ensures that the reading file descriptor does not change |
|
|
326 | it's value. |
|
|
327 | |
174 | =cut |
328 | =cut |
175 | |
329 | |
176 | 1; |
330 | 1; |
177 | |
331 | |
178 | =back |
332 | =back |
179 | |
333 | |
180 | =head1 EXAMPLE |
334 | =head1 EXAMPLE |
181 | |
335 | |
182 | #TODO |
336 | There really should be a complete C/XS example. Bug me about it. Better |
|
|
337 | yet, create one. |
183 | |
338 | |
184 | =head1 IMPLEMENTATION DETAILS AND LIMITATIONS |
339 | =head1 IMPLEMENTATION DETAILS AND LIMITATIONS |
185 | |
340 | |
186 | This module works by "hijacking" SIGKILL, which is guarenteed to be always |
341 | This module works by "hijacking" SIGKILL, which is guaranteed to always |
187 | available in perl, but also cannot be caught, so is always available. |
342 | exist, but also cannot be caught, so is always available. |
188 | |
343 | |
189 | Basically, this module fakes the receive of a SIGKILL signal and |
344 | Basically, this module fakes the occurance of a SIGKILL signal and |
190 | then catches it. This makes normal signal handling slower (probably |
345 | then intercepts the interpreter handling it. This makes normal signal |
191 | unmeasurably), but has the advantage of not requiring a special runops nor |
346 | handling slower (probably unmeasurably, though), but has the advantage |
192 | slowing down normal perl execution a bit. |
347 | of not requiring a special runops function, nor slowing down normal perl |
|
|
348 | execution a bit. |
193 | |
349 | |
194 | It assumes that C<sig_atomic_t> and C<int> are both exception-safe to |
350 | It assumes that C<sig_atomic_t>, C<int> and C<IV> are all async-safe to |
195 | modify (C<sig_atomic_> is used by this module, and perl itself uses |
351 | modify. |
196 | C<int>, so we can assume that this is quite portbale, at least w.r.t. |
|
|
197 | signals). |
|
|
198 | |
352 | |
199 | =head1 AUTHOR |
353 | =head1 AUTHOR |
200 | |
354 | |
201 | Marc Lehmann <schmorp@schmorp.de> |
355 | Marc Lehmann <schmorp@schmorp.de> |
202 | http://home.schmorp.de/ |
356 | http://home.schmorp.de/ |