… | |
… | |
53 | |
53 | |
54 | For example the deliantra game server uses a variant of this technique |
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 |
55 | to interrupt background processes regularly to send map updates to game |
56 | clients. |
56 | clients. |
57 | |
57 | |
|
|
58 | Or L<EV::Loop::Async> uses an interrupt object to wake up perl when new |
|
|
59 | events have arrived. |
|
|
60 | |
58 | L<IO::AIO> and L<BDB> could also use this to speed up result reporting. |
61 | L<IO::AIO> and L<BDB> could also use this to speed up result reporting. |
59 | |
62 | |
60 | =item Speedy event loop invocation |
63 | =item Speedy event loop invocation |
61 | |
64 | |
62 | One could use this module e.g. in L<Coro> to interrupt a running coro-thread |
65 | One could use this module e.g. in L<Coro> to interrupt a running coro-thread |
… | |
… | |
88 | I<running> interpreter, there is optional support for signalling a pipe |
91 | I<running> interpreter, there is optional support for signalling a pipe |
89 | - that means you can also wait for the pipe to become readable (e.g. via |
92 | - 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> |
93 | L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read> |
91 | and C<write> syscall. |
94 | and C<write> syscall. |
92 | |
95 | |
|
|
96 | =head1 USAGE EXAMPLES |
|
|
97 | |
|
|
98 | =head2 Async::Interrupt to implement race-free signal handling |
|
|
99 | |
|
|
100 | This example uses a single event pipe for all signals, and one |
|
|
101 | Async::Interrupt per signal. |
|
|
102 | |
|
|
103 | First, create the event pipe and hook it into the event loop (this code is |
|
|
104 | actually what L<AnyEvent> uses itself): |
|
|
105 | |
|
|
106 | $SIGPIPE = new Async::Interrupt::EventPipe; |
|
|
107 | $SIGPIPE_W = AnyEvent->io ( |
|
|
108 | fh => $SIGPIPE->fileno, |
|
|
109 | poll => "r", |
|
|
110 | cb => \&_signal_check, |
|
|
111 | ); |
|
|
112 | |
|
|
113 | Then, for each signal to hook, create an Async::Interrupt object. The |
|
|
114 | callback just sets a global variable, as we are only interested in |
|
|
115 | synchronous signals (i.e. when the event loop polls), which is why the |
|
|
116 | pipe draining is not done automatically. |
|
|
117 | |
|
|
118 | my $interrupt = new Async::Interrupt |
|
|
119 | cb => sub { undef $SIGNAL_RECEIVED{$signum} } |
|
|
120 | signal => $signal, |
|
|
121 | pipe => [$SIGPIPE_R->filenos], |
|
|
122 | pipe_autodrain => 0, |
|
|
123 | ; |
|
|
124 | |
|
|
125 | Finally, the I/O callback for the event pipe handles the signals: |
|
|
126 | |
|
|
127 | sub _signal_check { |
|
|
128 | # drain the pipe first |
|
|
129 | $SIGPIPE->drain; |
|
|
130 | |
|
|
131 | # two loops, just to be sure |
|
|
132 | while (%SIGNAL_RECEIVED) { |
|
|
133 | for (keys %SIGNAL_RECEIVED) { |
|
|
134 | delete $SIGNAL_RECEIVED{$_}; |
|
|
135 | warn "signal $_ received\n"; |
|
|
136 | } |
|
|
137 | } |
|
|
138 | } |
|
|
139 | |
|
|
140 | |
|
|
141 | |
|
|
142 | =head1 THE Async::Interrupt CLASS |
|
|
143 | |
93 | =over 4 |
144 | =over 4 |
94 | |
145 | |
95 | =cut |
146 | =cut |
96 | |
147 | |
97 | package Async::Interrupt; |
148 | package Async::Interrupt; |
98 | |
149 | |
99 | use common::sense; |
150 | use common::sense; |
100 | |
151 | |
101 | BEGIN { |
152 | BEGIN { |
|
|
153 | # the next line forces initialisation of internal |
|
|
154 | # signal handling # variables |
|
|
155 | $SIG{KILL} = sub { }; |
|
|
156 | |
102 | our $VERSION = '0.041'; |
157 | our $VERSION = '0.6'; |
103 | |
158 | |
104 | require XSLoader; |
159 | require XSLoader; |
105 | XSLoader::load Async::Interrupt::, $VERSION; |
160 | XSLoader::load ("Async::Interrupt", $VERSION); |
106 | } |
161 | } |
107 | |
162 | |
108 | our $DIED = sub { warn "$@" }; |
163 | our $DIED = sub { warn "$@" }; |
109 | |
164 | |
110 | =item $async = new Async::Interrupt key => value... |
165 | =item $async = new Async::Interrupt key => value... |
… | |
… | |
153 | might use (the exception is C<errno>, which is saved and restored by |
208 | might use (the exception is C<errno>, which is saved and restored by |
154 | Async::Interrupt). The callback itself runs as part of the perl context, |
209 | Async::Interrupt). The callback itself runs as part of the perl context, |
155 | so you can call any perl functions and modify any perl data structures (in |
210 | so you can call any perl functions and modify any perl data structures (in |
156 | which case the requirements set out for C<cb> apply as well). |
211 | which case the requirements set out for C<cb> apply as well). |
157 | |
212 | |
|
|
213 | =item var => $scalar_ref |
|
|
214 | |
|
|
215 | When specified, then the given argument must be a reference to a |
|
|
216 | scalar. The scalar will be set to C<0> initially. Signalling the interrupt |
|
|
217 | object will set it to the passed value, handling the interrupt will reset |
|
|
218 | it to C<0> again. |
|
|
219 | |
|
|
220 | Note that the only thing you are legally allowed to do is to is to check |
|
|
221 | the variable in a boolean or integer context (e.g. comparing it with a |
|
|
222 | string, or printing it, will I<destroy> it and might cause your program to |
|
|
223 | crash or worse). |
|
|
224 | |
158 | =item signal => $signame_or_value |
225 | =item signal => $signame_or_value |
159 | |
226 | |
160 | When this parameter is specified, then the Async::Interrupt will hook the |
227 | When this parameter is specified, then the Async::Interrupt will hook the |
161 | given signal, that is, it will effectively call C<< ->signal (0) >> each time |
228 | given signal, that is, it will effectively call C<< ->signal (0) >> each time |
162 | the given signal is caught by the process. |
229 | the given signal is caught by the process. |
… | |
… | |
171 | be written to it, and before the callback is being invoked, it will be |
238 | be written to it, and before the callback is being invoked, it will be |
172 | read again. Due to races, it is unlikely but possible that multiple octets |
239 | read again. Due to races, it is unlikely but possible that multiple octets |
173 | are written. It is required that the file handles are both in nonblocking |
240 | are written. It is required that the file handles are both in nonblocking |
174 | mode. |
241 | mode. |
175 | |
242 | |
176 | You can get a portable pipe and set non-blocking mode portably by using |
|
|
177 | e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution. |
|
|
178 | |
|
|
179 | It is also possible to pass in a linux eventfd as both read and write |
|
|
180 | handle (which is faster than a pipe). |
|
|
181 | |
|
|
182 | The object will keep a reference to the file handles. |
243 | The object will keep a reference to the file handles. |
183 | |
244 | |
184 | This can be used to ensure that async notifications will interrupt event |
245 | This can be used to ensure that async notifications will interrupt event |
185 | frameworks as well. |
246 | frameworks as well. |
186 | |
247 | |
|
|
248 | Note that C<Async::Interrupt> will create a suitable signal fd |
|
|
249 | automatically when your program requests one, so you don't have to specify |
|
|
250 | this argument when all you want is an extra file descriptor to watch. |
|
|
251 | |
|
|
252 | If you want to share a single event pipe between multiple Async::Interrupt |
|
|
253 | objects, you can use the C<Async::Interrupt::EventPipe> class to manage |
|
|
254 | those. |
|
|
255 | |
187 | =back |
256 | =back |
188 | |
257 | |
189 | =cut |
258 | =cut |
190 | |
259 | |
191 | sub new { |
260 | sub new { |
192 | my ($class, %arg) = @_; |
261 | my ($class, %arg) = @_; |
193 | |
262 | |
194 | bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}), $class |
263 | bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class |
195 | } |
264 | } |
196 | |
265 | |
197 | =item ($signal_func, $signal_arg) = $async->signal_func |
266 | =item ($signal_func, $signal_arg) = $async->signal_func |
198 | |
267 | |
199 | Returns the address of a function to call asynchronously. The function has |
268 | Returns the address of a function to call asynchronously. The function |
200 | the following prototype and needs to be passed the specified C<$c_arg>, |
269 | has the following prototype and needs to be passed the specified |
201 | which is a C<void *> cast to C<IV>: |
270 | C<$signal_arg>, which is a C<void *> cast to C<IV>: |
202 | |
271 | |
203 | void (*signal_func) (void *signal_arg, int value) |
272 | void (*signal_func) (void *signal_arg, int value) |
204 | |
273 | |
205 | An example call would look like: |
274 | An example call would look like: |
206 | |
275 | |
207 | signal_func (signal_arg, 0); |
276 | signal_func (signal_arg, 0); |
208 | |
277 | |
209 | The function is safe to call from within signal and thread contexts, at |
278 | The function is safe to call from within signal and thread contexts, at |
210 | any time. The specified C<value> is passed to both C and Perl callback. |
279 | any time. The specified C<value> is passed to both C and Perl callback. |
211 | |
280 | |
212 | C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is |
281 | C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0> |
213 | portable). |
282 | (1..127 is portable). |
214 | |
283 | |
215 | If the function is called while the Async::Interrupt object is already |
284 | If the function is called while the Async::Interrupt object is already |
216 | signaled but before the callbacks are being executed, then the stored |
285 | signaled but before the callbacks are being executed, then the stored |
217 | C<value> is either the old or the new one. Due to the asynchronous |
286 | C<value> is either the old or the new one. Due to the asynchronous |
218 | nature of the code, the C<value> can even be passed to two consecutive |
287 | nature of the code, the C<value> can even be passed to two consecutive |
219 | invocations of the callback. |
288 | invocations of the callback. |
220 | |
289 | |
|
|
290 | =item $address = $async->c_var |
|
|
291 | |
|
|
292 | Returns the address (cast to IV) of an C<IV> variable. The variable is set |
|
|
293 | to C<0> initially and gets set to the passed value whenever the object |
|
|
294 | gets signalled, and reset to C<0> once the interrupt has been handled. |
|
|
295 | |
|
|
296 | Note that it is often beneficial to just call C<PERL_ASYNC_CHECK ()> to |
|
|
297 | handle any interrupts. |
|
|
298 | |
|
|
299 | Example: call some XS function to store the address, then show C code |
|
|
300 | waiting for it. |
|
|
301 | |
|
|
302 | my_xs_func $async->c_var; |
|
|
303 | |
|
|
304 | static IV *valuep; |
|
|
305 | |
|
|
306 | void |
|
|
307 | my_xs_func (void *addr) |
|
|
308 | CODE: |
|
|
309 | valuep = (IV *)addr; |
|
|
310 | |
|
|
311 | // code in a loop, waiting |
|
|
312 | while (!*valuep) |
|
|
313 | ; // do something |
|
|
314 | |
221 | =item $async->signal ($value=0) |
315 | =item $async->signal ($value=1) |
222 | |
316 | |
223 | This signals the given async object from Perl code. Semi-obviously, this |
317 | This signals the given async object from Perl code. Semi-obviously, this |
224 | will instantly trigger the callback invocation. |
318 | will instantly trigger the callback invocation (it does not, as the name |
|
|
319 | might imply, do anything with POSIX signals). |
225 | |
320 | |
226 | C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is |
321 | C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0> |
227 | portable). |
322 | (1..127 is portable). |
|
|
323 | |
|
|
324 | =item $async->signal_hysteresis ($enable) |
|
|
325 | |
|
|
326 | Enables or disables signal hysteresis (default: disabled). If a POSIX |
|
|
327 | signal is used as a signal source for the interrupt object, then enabling |
|
|
328 | signal hysteresis causes Async::Interrupt to reset the signal action to |
|
|
329 | C<SIG_IGN> in the signal handler and restore it just before handling the |
|
|
330 | interruption. |
|
|
331 | |
|
|
332 | When you expect a lot of signals (e.g. when using SIGIO), then enabling |
|
|
333 | signal hysteresis can reduce the number of handler invocations |
|
|
334 | considerably, at the cost of two extra syscalls. |
|
|
335 | |
|
|
336 | Note that setting the signal to C<SIG_IGN> can have unintended side |
|
|
337 | effects when you fork and exec other programs, as often they do nto expect |
|
|
338 | signals to be ignored by default. |
228 | |
339 | |
229 | =item $async->block |
340 | =item $async->block |
230 | |
341 | |
231 | =item $async->unblock |
342 | =item $async->unblock |
232 | |
343 | |
… | |
… | |
247 | This call C<< $async->block >> and installs a handler that is called when |
358 | This call C<< $async->block >> and installs a handler that is called when |
248 | the current scope is exited (via an exception, by canceling the Coro |
359 | the current scope is exited (via an exception, by canceling the Coro |
249 | thread, by calling last/goto etc.). |
360 | thread, by calling last/goto etc.). |
250 | |
361 | |
251 | This is the recommended (and fastest) way to implement critical sections. |
362 | This is the recommended (and fastest) way to implement critical sections. |
|
|
363 | |
|
|
364 | =item ($block_func, $block_arg) = $async->scope_block_func |
|
|
365 | |
|
|
366 | Returns the address of a function that implements the C<scope_block> |
|
|
367 | functionality. |
|
|
368 | |
|
|
369 | It has the following prototype and needs to be passed the specified |
|
|
370 | C<$block_arg>, which is a C<void *> cast to C<IV>: |
|
|
371 | |
|
|
372 | void (*block_func) (void *block_arg) |
|
|
373 | |
|
|
374 | An example call would look like: |
|
|
375 | |
|
|
376 | block_func (block_arg); |
|
|
377 | |
|
|
378 | The function is safe to call only from within the toplevel of a perl XS |
|
|
379 | function and will call C<LEAVE> and C<ENTER> (in this order!). |
252 | |
380 | |
253 | =item $async->pipe_enable |
381 | =item $async->pipe_enable |
254 | |
382 | |
255 | =item $async->pipe_disable |
383 | =item $async->pipe_disable |
256 | |
384 | |
… | |
… | |
258 | enabled). Writing to a pipe is relatively expensive, so it can be disabled |
386 | enabled). Writing to a pipe is relatively expensive, so it can be disabled |
259 | when you know you are not waiting for it (for example, with L<EV> you |
387 | when you know you are not waiting for it (for example, with L<EV> you |
260 | could disable the pipe in a check watcher, and enable it in a prepare |
388 | could disable the pipe in a check watcher, and enable it in a prepare |
261 | watcher). |
389 | watcher). |
262 | |
390 | |
263 | Note that when C<fd_disable> is in effect, no attempt to read from the |
391 | Note that currently, while C<pipe_disable> is in effect, no attempt to |
264 | pipe will be done. |
392 | read from the pipe will be done when handling events. This might change as |
|
|
393 | soon as I realize why this is a mistake. |
|
|
394 | |
|
|
395 | =item $fileno = $async->pipe_fileno |
|
|
396 | |
|
|
397 | Returns the reading side of the signalling pipe. If no signalling pipe is |
|
|
398 | currently attached to the object, it will dynamically create one. |
|
|
399 | |
|
|
400 | Note that the only valid oepration on this file descriptor is to wait |
|
|
401 | until it is readable. The fd might belong currently to a pipe, a tcp |
|
|
402 | socket, or an eventfd, depending on the platform, and is guaranteed to be |
|
|
403 | C<select>able. |
|
|
404 | |
|
|
405 | =item $async->pipe_autodrain ($enable) |
|
|
406 | |
|
|
407 | Enables (C<1>) or disables (C<0>) automatic draining of the pipe (default: |
|
|
408 | enabled). When automatic draining is enabled, then Async::Interrupt will |
|
|
409 | automatically clear the pipe. Otherwise the user is responsible for this |
|
|
410 | draining. |
|
|
411 | |
|
|
412 | This is useful when you want to share one pipe among many Async::Interrupt |
|
|
413 | objects. |
|
|
414 | |
|
|
415 | =item $async->post_fork |
|
|
416 | |
|
|
417 | The object will not normally be usable after a fork (as the pipe fd is |
|
|
418 | shared between processes). Calling this method after a fork in the child |
|
|
419 | ensures that the object will work as expected again. It only needs to be |
|
|
420 | called when the async object is used in the child. |
|
|
421 | |
|
|
422 | This only works when the pipe was created by Async::Interrupt. |
|
|
423 | |
|
|
424 | Async::Interrupt ensures that the reading file descriptor does not change |
|
|
425 | it's value. |
|
|
426 | |
|
|
427 | =item $signum = Async::Interrupt::sig2num $signame_or_number |
|
|
428 | |
|
|
429 | =item $signame = Async::Interrupt::sig2name $signame_or_number |
|
|
430 | |
|
|
431 | These two convenience functions simply convert a signal name or number to |
|
|
432 | the corresponding name or number. They are not used by this module and |
|
|
433 | exist just because perl doesn't have a nice way to do this on its own. |
|
|
434 | |
|
|
435 | They will return C<undef> on illegal names or numbers. |
|
|
436 | |
|
|
437 | =back |
|
|
438 | |
|
|
439 | =head1 THE Async::Interrupt::EventPipe CLASS |
|
|
440 | |
|
|
441 | Pipes are the predominent utility to make asynchronous signals |
|
|
442 | synchronous. However, pipes are hard to come by: they don't exist on the |
|
|
443 | broken windows platform, and on GNU/Linux systems, you might want to use |
|
|
444 | an C<eventfd> instead. |
|
|
445 | |
|
|
446 | This class creates selectable event pipes in a portable fashion: on |
|
|
447 | windows, it will try to create a tcp socket pair, on GNU/Linux, it will |
|
|
448 | try to create an eventfd and everywhere else it will try to use a normal |
|
|
449 | pipe. |
|
|
450 | |
|
|
451 | =over 4 |
|
|
452 | |
|
|
453 | =item $epipe = new Async::Interrupt::EventPipe |
|
|
454 | |
|
|
455 | This creates and returns an eventpipe object. This object is simply a |
|
|
456 | blessed array reference: |
|
|
457 | |
|
|
458 | =item ($r_fd, $w_fd) = $epipe->filenos |
|
|
459 | |
|
|
460 | Returns the read-side file descriptor and the write-side file descriptor. |
|
|
461 | |
|
|
462 | Example: pass an eventpipe object as pipe to the Async::Interrupt |
|
|
463 | constructor, and create an AnyEvent watcher for the read side. |
|
|
464 | |
|
|
465 | my $epipe = new Async::Interrupt::EventPipe; |
|
|
466 | my $asy = new Async::Interrupt pipe => [$epipe->filenos]; |
|
|
467 | my $iow = AnyEvent->io (fh => $epipe->fileno, poll => 'r', cb => sub { }); |
|
|
468 | |
|
|
469 | =item $r_fd = $epipe->fileno |
|
|
470 | |
|
|
471 | Return only the reading/listening side. |
|
|
472 | |
|
|
473 | =item $epipe->signal |
|
|
474 | |
|
|
475 | Write something to the pipe, in a portable fashion. |
|
|
476 | |
|
|
477 | =item $epipe->drain |
|
|
478 | |
|
|
479 | Drain (empty) the pipe. |
|
|
480 | |
|
|
481 | =item $epipe->renew |
|
|
482 | |
|
|
483 | Recreates the pipe (useful after a fork). The reading side will not change |
|
|
484 | it's file descriptor number, but the writing side might. |
|
|
485 | |
|
|
486 | =back |
265 | |
487 | |
266 | =cut |
488 | =cut |
267 | |
489 | |
268 | 1; |
490 | 1; |
269 | |
|
|
270 | =back |
|
|
271 | |
491 | |
272 | =head1 EXAMPLE |
492 | =head1 EXAMPLE |
273 | |
493 | |
274 | There really should be a complete C/XS example. Bug me about it. Better |
494 | There really should be a complete C/XS example. Bug me about it. Better |
275 | yet, create one. |
495 | yet, create one. |
… | |
… | |
283 | then intercepts the interpreter handling it. This makes normal signal |
503 | then intercepts the interpreter handling it. This makes normal signal |
284 | handling slower (probably unmeasurably, though), but has the advantage |
504 | handling slower (probably unmeasurably, though), but has the advantage |
285 | of not requiring a special runops function, nor slowing down normal perl |
505 | of not requiring a special runops function, nor slowing down normal perl |
286 | execution a bit. |
506 | execution a bit. |
287 | |
507 | |
288 | It assumes that C<sig_atomic_t> and C<int> are both async-safe to modify |
508 | It assumes that C<sig_atomic_t>, C<int> and C<IV> are all async-safe to |
289 | (C<sig_atomic_> is used by this module, and perl itself uses C<int>, so we |
509 | modify. |
290 | can assume that this is quite portable, at least w.r.t. signals). |
|
|
291 | |
510 | |
292 | =head1 AUTHOR |
511 | =head1 AUTHOR |
293 | |
512 | |
294 | Marc Lehmann <schmorp@schmorp.de> |
513 | Marc Lehmann <schmorp@schmorp.de> |
295 | http://home.schmorp.de/ |
514 | http://home.schmorp.de/ |