… | |
… | |
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 | Or L<EV::Loop::Async> uses an interrupt object to wake up perl when new |
|
|
59 | events have arrived. |
|
|
60 | |
|
|
61 | L<IO::AIO> and L<BDB> could also use this to speed up result reporting. |
|
|
62 | |
|
|
63 | =item Speedy event loop invocation |
|
|
64 | |
|
|
65 | One could use this module e.g. in L<Coro> to interrupt a running coro-thread |
|
|
66 | and cause it to enter the event loop. |
|
|
67 | |
|
|
68 | Or one could bind to C<SIGIO> and tell some important sockets to send this |
|
|
69 | signal, causing the event loop to be entered to reduce network latency. |
|
|
70 | |
|
|
71 | =back |
|
|
72 | |
|
|
73 | =head2 HOW TO USE |
|
|
74 | |
|
|
75 | You can use this module by creating an C<Async::Interrupt> object for each |
|
|
76 | such event source. This object stores a perl and/or a C-level callback |
|
|
77 | that is invoked when the C<Async::Interrupt> object gets signalled. It is |
|
|
78 | executed at the next time the perl interpreter is running (i.e. it will |
|
|
79 | interrupt a computation, but not an XS function or a syscall). |
31 | |
80 | |
32 | You can signal the C<Async::Interrupt> object either by calling it's C<< |
81 | 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. |
82 | ->signal >> method, or, more commonly, by calling a C function. There is |
|
|
83 | also the built-in (POSIX) signal source. |
34 | |
84 | |
35 | The C<< ->signal_func >> returns the address of the C function that is to |
85 | 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 |
86 | 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 |
87 | function also takes an integer argument in the range SIG_ATOMIC_MIN to |
38 | SIG_ATOMIC_MAX (guaranteed to allow at least 0..127). |
88 | SIG_ATOMIC_MAX (guaranteed to allow at least 0..127). |
39 | |
89 | |
40 | Since this kind of interruption is fast, but can only interrupt a |
90 | Since this kind of interruption is fast, but can only interrupt a |
41 | I<running> interpreter, there is optional support for also signalling a |
91 | 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 (e.g. |
92 | - that means you can also wait for the pipe to become readable (e.g. via |
43 | via L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a |
93 | L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read> |
44 | C<read> and C<write> syscall. |
94 | and C<write> syscall. |
|
|
95 | |
|
|
96 | =head1 USAGE EXAMPLES |
|
|
97 | |
|
|
98 | =head2 Implementing race-free signal handling |
|
|
99 | |
|
|
100 | This example uses a single event pipe for all signals, and one |
|
|
101 | Async::Interrupt per signal. This code is actually what the L<AnyEvent> |
|
|
102 | module uses itself when Async::Interrupt is available. |
|
|
103 | |
|
|
104 | First, create the event pipe and hook it into the event loop |
|
|
105 | |
|
|
106 | $SIGPIPE = new Async::Interrupt::EventPipe; |
|
|
107 | $SIGPIPE_W = AnyEvent->io ( |
|
|
108 | fh => $SIGPIPE->fileno, |
|
|
109 | poll => "r", |
|
|
110 | cb => \&_signal_check, # defined later |
|
|
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 => $signum, |
|
|
121 | pipe => [$SIGPIPE->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 | =head2 Interrupt perl from another thread |
|
|
141 | |
|
|
142 | This example interrupts the Perl interpreter from another thread, via the |
|
|
143 | XS API. This is used by e.g. the L<EV::Loop::Async> module. |
|
|
144 | |
|
|
145 | On the Perl level, a new loop object (which contains the thread) |
|
|
146 | is created, by first calling some XS constructor, querying the |
|
|
147 | C-level callback function and feeding that as the C<c_cb> into the |
|
|
148 | Async::Interrupt constructor: |
|
|
149 | |
|
|
150 | my $self = XS_thread_constructor; |
|
|
151 | my ($c_func, $c_arg) = _c_func $self; # return the c callback |
|
|
152 | my $asy = new Async::Interrupt c_cb => [$c_func, $c_arg]; |
|
|
153 | |
|
|
154 | Then the newly created Interrupt object is queried for the signaling |
|
|
155 | function that the newly created thread should call, and this is in turn |
|
|
156 | told to the thread object: |
|
|
157 | |
|
|
158 | _attach $self, $asy->signal_func; |
|
|
159 | |
|
|
160 | So to repeat: first the XS object is created, then it is queried for the |
|
|
161 | callback that should be called when the Interrupt object gets signalled. |
|
|
162 | |
|
|
163 | Then the interrupt object is queried for the callback fucntion that the |
|
|
164 | thread should call to signal the Interrupt object, and this callback is |
|
|
165 | then attached to the thread. |
|
|
166 | |
|
|
167 | You have to be careful that your new thread is not signalling before the |
|
|
168 | signal function was configured, for example by starting the background |
|
|
169 | thread only within C<_attach>. |
|
|
170 | |
|
|
171 | That concludes the Perl part. |
|
|
172 | |
|
|
173 | The XS part consists of the actual constructor which creates a thread, |
|
|
174 | which is not relevant for this example, and two functions, C<_c_func>, |
|
|
175 | which returns the Perl-side callback, and C<_attach>, which configures |
|
|
176 | the signalling functioon that is safe toc all from another thread. For |
|
|
177 | simplicity, we will use global variables to store the functions, normally |
|
|
178 | you would somehow attach them to C<$self>. |
|
|
179 | |
|
|
180 | The C<c_func> simply returns the address of a static function and arranges |
|
|
181 | for the object pointed to by C<$self> to be passed to it, as an integer: |
|
|
182 | |
|
|
183 | void |
|
|
184 | _c_func (SV *loop) |
|
|
185 | PPCODE: |
|
|
186 | EXTEND (SP, 2); |
|
|
187 | PUSHs (sv_2mortal (newSViv (PTR2IV (c_func)))); |
|
|
188 | PUSHs (sv_2mortal (newSViv (SvRV (loop)))); |
|
|
189 | |
|
|
190 | This would be the callback (since it runs in a normal Perl context, it is |
|
|
191 | permissible to manipulate Perl values): |
|
|
192 | |
|
|
193 | static void |
|
|
194 | c_func (pTHX_ void *loop_, int value) |
|
|
195 | { |
|
|
196 | SV *loop_object = (SV *)loop_; |
|
|
197 | ... |
|
|
198 | } |
|
|
199 | |
|
|
200 | And this attaches the signalling callback: |
|
|
201 | |
|
|
202 | static void (*my_sig_func) (void *signal_arg, int value); |
|
|
203 | static void *my_sig_arg; |
|
|
204 | |
|
|
205 | void |
|
|
206 | _attach (SV *loop_, IV sig_func, void *sig_arg) |
|
|
207 | CODE: |
|
|
208 | { |
|
|
209 | my_sig_func = sig_func; |
|
|
210 | my_sig_arg = sig_arg; |
|
|
211 | |
|
|
212 | /* now run the thread */ |
|
|
213 | thread_create (&u->tid, l_run, 0); |
|
|
214 | } |
|
|
215 | |
|
|
216 | And C<l_run> (the background thread) would eventually call the signaling |
|
|
217 | function: |
|
|
218 | |
|
|
219 | my_sig_func (my_sig_arg, 0); |
|
|
220 | |
|
|
221 | You can have a look at L<EV::Loop::Async> for an actual example using |
|
|
222 | intra-thread communication, locking and so on. |
|
|
223 | |
|
|
224 | |
|
|
225 | =head1 THE Async::Interrupt CLASS |
45 | |
226 | |
46 | =over 4 |
227 | =over 4 |
47 | |
228 | |
48 | =cut |
229 | =cut |
49 | |
230 | |
50 | package Async::Interrupt; |
231 | package Async::Interrupt; |
51 | |
232 | |
52 | no warnings; |
233 | use common::sense; |
53 | |
234 | |
54 | BEGIN { |
235 | BEGIN { |
|
|
236 | # the next line forces initialisation of internal |
|
|
237 | # signal handling variables, otherwise, PL_sig_pending |
|
|
238 | # etc. might be null pointers. |
|
|
239 | $SIG{KILL} = sub { }; |
|
|
240 | |
55 | $VERSION = '0.04'; |
241 | our $VERSION = '1.05'; |
56 | |
242 | |
57 | require XSLoader; |
243 | require XSLoader; |
58 | XSLoader::load Async::Interrupt::, $VERSION; |
244 | XSLoader::load ("Async::Interrupt", $VERSION); |
59 | } |
245 | } |
60 | |
246 | |
61 | our $DIED = sub { warn "$@" }; |
247 | our $DIED = sub { warn "$@" }; |
62 | |
248 | |
63 | =item $async = new Async::Interrupt key => value... |
249 | =item $async = new Async::Interrupt key => value... |
… | |
… | |
83 | The exceptions are C<$!> and C<$@>, which are saved and restored by |
269 | The exceptions are C<$!> and C<$@>, which are saved and restored by |
84 | Async::Interrupt. |
270 | Async::Interrupt. |
85 | |
271 | |
86 | If the callback should throw an exception, then it will be caught, |
272 | If the callback should throw an exception, then it will be caught, |
87 | and C<$Async::Interrupt::DIED> will be called with C<$@> containing |
273 | and C<$Async::Interrupt::DIED> will be called with C<$@> containing |
88 | the exception. The default will simply C<warn> about the message and |
274 | the exception. The default will simply C<warn> about the message and |
89 | continue. |
275 | continue. |
90 | |
276 | |
91 | =item c_cb => [$c_func, $c_arg] |
277 | =item c_cb => [$c_func, $c_arg] |
92 | |
278 | |
93 | Registers a C callback the be invoked whenever the async interrupt is |
279 | Registers a C callback the be invoked whenever the async interrupt is |
… | |
… | |
106 | might use (the exception is C<errno>, which is saved and restored by |
292 | might use (the exception is C<errno>, which is saved and restored by |
107 | Async::Interrupt). The callback itself runs as part of the perl context, |
293 | Async::Interrupt). The callback itself runs as part of the perl context, |
108 | so you can call any perl functions and modify any perl data structures (in |
294 | so you can call any perl functions and modify any perl data structures (in |
109 | which case the requirements set out for C<cb> apply as well). |
295 | which case the requirements set out for C<cb> apply as well). |
110 | |
296 | |
|
|
297 | =item var => $scalar_ref |
|
|
298 | |
|
|
299 | When specified, then the given argument must be a reference to a |
|
|
300 | scalar. The scalar will be set to C<0> initially. Signalling the interrupt |
|
|
301 | object will set it to the passed value, handling the interrupt will reset |
|
|
302 | it to C<0> again. |
|
|
303 | |
|
|
304 | Note that the only thing you are legally allowed to do is to is to check |
|
|
305 | the variable in a boolean or integer context (e.g. comparing it with a |
|
|
306 | string, or printing it, will I<destroy> it and might cause your program to |
|
|
307 | crash or worse). |
|
|
308 | |
111 | =item signal => $signame_or_value |
309 | =item signal => $signame_or_value |
112 | |
310 | |
113 | When this parameter is specified, then the Async::Interrupt will hook the |
311 | When this parameter is specified, then the Async::Interrupt will hook the |
114 | given signal, that is, it will effectively call C<< ->signal (0) >> each time |
312 | given signal, that is, it will effectively call C<< ->signal (0) >> each time |
115 | the given signal is caught by the process. |
313 | the given signal is caught by the process. |
116 | |
314 | |
117 | Only one async can hook a given signal, and the signal will be restored to |
315 | Only one async can hook a given signal, and the signal will be restored to |
118 | defaults when the Async::Interrupt object gets destroyed. |
316 | defaults when the Async::Interrupt object gets destroyed. |
|
|
317 | |
|
|
318 | =item signal_hysteresis => $boolean |
|
|
319 | |
|
|
320 | Sets the initial signal hysteresis state, see the C<signal_hysteresis> |
|
|
321 | method, below. |
119 | |
322 | |
120 | =item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] |
323 | =item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] |
121 | |
324 | |
122 | Specifies two file descriptors (or file handles) that should be signalled |
325 | Specifies two file descriptors (or file handles) that should be signalled |
123 | whenever the async interrupt is signalled. This means a single octet will |
326 | whenever the async interrupt is signalled. This means a single octet will |
124 | be written to it, and before the callback is being invoked, it will be |
327 | be written to it, and before the callback is being invoked, it will be |
125 | read again. Due to races, it is unlikely but possible that multiple octets |
328 | read again. Due to races, it is unlikely but possible that multiple octets |
126 | are written. It is required that the file handles are both in nonblocking |
329 | are written. It is required that the file handles are both in nonblocking |
127 | mode. |
330 | mode. |
128 | |
331 | |
129 | You can get a portable pipe and set non-blocking mode portably by using |
|
|
130 | e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution. |
|
|
131 | |
|
|
132 | It is also possible to pass in a linux eventfd as both read and write |
|
|
133 | handle (which is faster than a pipe). |
|
|
134 | |
|
|
135 | The object will keep a reference to the file handles. |
332 | The object will keep a reference to the file handles. |
136 | |
333 | |
137 | This can be used to ensure that async notifications will interrupt event |
334 | This can be used to ensure that async notifications will interrupt event |
138 | frameworks as well. |
335 | frameworks as well. |
139 | |
336 | |
|
|
337 | Note that C<Async::Interrupt> will create a suitable signal fd |
|
|
338 | automatically when your program requests one, so you don't have to specify |
|
|
339 | this argument when all you want is an extra file descriptor to watch. |
|
|
340 | |
|
|
341 | If you want to share a single event pipe between multiple Async::Interrupt |
|
|
342 | objects, you can use the C<Async::Interrupt::EventPipe> class to manage |
|
|
343 | those. |
|
|
344 | |
|
|
345 | =item pipe_autodrain => $boolean |
|
|
346 | |
|
|
347 | Sets the initial autodrain state, see the C<pipe_autodrain> method, below. |
|
|
348 | |
140 | =back |
349 | =back |
141 | |
350 | |
142 | =cut |
351 | =cut |
143 | |
352 | |
144 | sub new { |
353 | sub new { |
145 | my ($class, %arg) = @_; |
354 | my ($class, %arg) = @_; |
146 | |
355 | |
147 | bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}), $class |
356 | my $self = bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class; |
|
|
357 | |
|
|
358 | # urgs, reminds me of Event |
|
|
359 | for my $attr (qw(pipe_autodrain signal_hysteresis)) { |
|
|
360 | $self->$attr ($arg{$attr}) if exists $arg{$attr}; |
|
|
361 | } |
|
|
362 | |
|
|
363 | $self |
148 | } |
364 | } |
149 | |
365 | |
150 | =item ($signal_func, $signal_arg) = $async->signal_func |
366 | =item ($signal_func, $signal_arg) = $async->signal_func |
151 | |
367 | |
152 | Returns the address of a function to call asynchronously. The function has |
368 | Returns the address of a function to call asynchronously. The function |
153 | the following prototype and needs to be passed the specified C<$c_arg>, |
369 | has the following prototype and needs to be passed the specified |
154 | which is a C<void *> cast to C<IV>: |
370 | C<$signal_arg>, which is a C<void *> cast to C<IV>: |
155 | |
371 | |
156 | void (*signal_func) (void *signal_arg, int value) |
372 | void (*signal_func) (void *signal_arg, int value) |
157 | |
373 | |
158 | An example call would look like: |
374 | An example call would look like: |
159 | |
375 | |
160 | signal_func (signal_arg, 0); |
376 | signal_func (signal_arg, 0); |
161 | |
377 | |
162 | The function is safe to call from within signal and thread contexts, at |
378 | The function is safe to call from within signal and thread contexts, at |
163 | any time. The specified C<value> is passed to both C and Perl callback. |
379 | any time. The specified C<value> is passed to both C and Perl callback. |
164 | |
380 | |
165 | C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is |
381 | C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0> |
166 | portable). |
382 | (1..127 is portable). |
167 | |
383 | |
168 | If the function is called while the Async::Interrupt object is already |
384 | If the function is called while the Async::Interrupt object is already |
169 | signaled but before the callbacks are being executed, then the stored |
385 | signaled but before the callbacks are being executed, then the stored |
170 | C<value> is either the old or the new one. Due to the asynchronous |
386 | C<value> is either the old or the new one. Due to the asynchronous |
171 | nature of the code, the C<value> can even be passed to two consecutive |
387 | nature of the code, the C<value> can even be passed to two consecutive |
172 | invocations of the callback. |
388 | invocations of the callback. |
173 | |
389 | |
|
|
390 | =item $address = $async->c_var |
|
|
391 | |
|
|
392 | Returns the address (cast to IV) of an C<IV> variable. The variable is set |
|
|
393 | to C<0> initially and gets set to the passed value whenever the object |
|
|
394 | gets signalled, and reset to C<0> once the interrupt has been handled. |
|
|
395 | |
|
|
396 | Note that it is often beneficial to just call C<PERL_ASYNC_CHECK ()> to |
|
|
397 | handle any interrupts. |
|
|
398 | |
|
|
399 | Example: call some XS function to store the address, then show C code |
|
|
400 | waiting for it. |
|
|
401 | |
|
|
402 | my_xs_func $async->c_var; |
|
|
403 | |
|
|
404 | static IV *valuep; |
|
|
405 | |
|
|
406 | void |
|
|
407 | my_xs_func (void *addr) |
|
|
408 | CODE: |
|
|
409 | valuep = (IV *)addr; |
|
|
410 | |
|
|
411 | // code in a loop, waiting |
|
|
412 | while (!*valuep) |
|
|
413 | ; // do something |
|
|
414 | |
174 | =item $async->signal ($value=0) |
415 | =item $async->signal ($value=1) |
175 | |
416 | |
176 | This signals the given async object from Perl code. Semi-obviously, this |
417 | This signals the given async object from Perl code. Semi-obviously, this |
177 | will instantly trigger the callback invocation. |
418 | will instantly trigger the callback invocation (it does not, as the name |
|
|
419 | might imply, do anything with POSIX signals). |
178 | |
420 | |
179 | C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is |
421 | C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0> |
180 | portable). |
422 | (1..127 is portable). |
|
|
423 | |
|
|
424 | =item $async->handle |
|
|
425 | |
|
|
426 | Calls the callback if the object is pending. |
|
|
427 | |
|
|
428 | This method does not need to be called normally, as it will be invoked |
|
|
429 | automatically. However, it can be used to force handling of outstanding |
|
|
430 | interrupts while the object is blocked. |
|
|
431 | |
|
|
432 | One reason why one might want to do that is when you want to switch |
|
|
433 | from asynchronous interruptions to synchronous one, using e.g. an event |
|
|
434 | loop. To do that, one would first C<< $async->block >> the interrupt |
|
|
435 | object, then register a read watcher on the C<pipe_fileno> that calls C<< |
|
|
436 | $async->handle >>. |
|
|
437 | |
|
|
438 | This disables asynchronous interruptions, but ensures that interrupts are |
|
|
439 | handled by the event loop. |
|
|
440 | |
|
|
441 | =item $async->signal_hysteresis ($enable) |
|
|
442 | |
|
|
443 | Enables or disables signal hysteresis (default: disabled). If a POSIX |
|
|
444 | signal is used as a signal source for the interrupt object, then enabling |
|
|
445 | signal hysteresis causes Async::Interrupt to reset the signal action to |
|
|
446 | C<SIG_IGN> in the signal handler and restore it just before handling the |
|
|
447 | interruption. |
|
|
448 | |
|
|
449 | When you expect a lot of signals (e.g. when using SIGIO), then enabling |
|
|
450 | signal hysteresis can reduce the number of handler invocations |
|
|
451 | considerably, at the cost of two extra syscalls. |
|
|
452 | |
|
|
453 | Note that setting the signal to C<SIG_IGN> can have unintended side |
|
|
454 | effects when you fork and exec other programs, as often they do not expect |
|
|
455 | signals to be ignored by default. |
181 | |
456 | |
182 | =item $async->block |
457 | =item $async->block |
183 | |
458 | |
184 | =item $async->unblock |
459 | =item $async->unblock |
185 | |
460 | |
… | |
… | |
200 | This call C<< $async->block >> and installs a handler that is called when |
475 | This call C<< $async->block >> and installs a handler that is called when |
201 | the current scope is exited (via an exception, by canceling the Coro |
476 | the current scope is exited (via an exception, by canceling the Coro |
202 | thread, by calling last/goto etc.). |
477 | thread, by calling last/goto etc.). |
203 | |
478 | |
204 | This is the recommended (and fastest) way to implement critical sections. |
479 | This is the recommended (and fastest) way to implement critical sections. |
|
|
480 | |
|
|
481 | =item ($block_func, $block_arg) = $async->scope_block_func |
|
|
482 | |
|
|
483 | Returns the address of a function that implements the C<scope_block> |
|
|
484 | functionality. |
|
|
485 | |
|
|
486 | It has the following prototype and needs to be passed the specified |
|
|
487 | C<$block_arg>, which is a C<void *> cast to C<IV>: |
|
|
488 | |
|
|
489 | void (*block_func) (void *block_arg) |
|
|
490 | |
|
|
491 | An example call would look like: |
|
|
492 | |
|
|
493 | block_func (block_arg); |
|
|
494 | |
|
|
495 | The function is safe to call only from within the toplevel of a perl XS |
|
|
496 | function and will call C<LEAVE> and C<ENTER> (in this order!). |
205 | |
497 | |
206 | =item $async->pipe_enable |
498 | =item $async->pipe_enable |
207 | |
499 | |
208 | =item $async->pipe_disable |
500 | =item $async->pipe_disable |
209 | |
501 | |
… | |
… | |
211 | enabled). Writing to a pipe is relatively expensive, so it can be disabled |
503 | enabled). Writing to a pipe is relatively expensive, so it can be disabled |
212 | when you know you are not waiting for it (for example, with L<EV> you |
504 | when you know you are not waiting for it (for example, with L<EV> you |
213 | could disable the pipe in a check watcher, and enable it in a prepare |
505 | could disable the pipe in a check watcher, and enable it in a prepare |
214 | watcher). |
506 | watcher). |
215 | |
507 | |
216 | Note that when C<fd_disable> is in effect, no attempt to read from the |
508 | Note that currently, while C<pipe_disable> is in effect, no attempt to |
217 | pipe will be done. |
509 | read from the pipe will be done when handling events. This might change as |
|
|
510 | soon as I realize why this is a mistake. |
|
|
511 | |
|
|
512 | =item $fileno = $async->pipe_fileno |
|
|
513 | |
|
|
514 | Returns the reading side of the signalling pipe. If no signalling pipe is |
|
|
515 | currently attached to the object, it will dynamically create one. |
|
|
516 | |
|
|
517 | Note that the only valid operation on this file descriptor is to wait |
|
|
518 | until it is readable. The fd might belong currently to a pipe, a tcp |
|
|
519 | socket, or an eventfd, depending on the platform, and is guaranteed to be |
|
|
520 | C<select>able. |
|
|
521 | |
|
|
522 | =item $async->pipe_autodrain ($enable) |
|
|
523 | |
|
|
524 | Enables (C<1>) or disables (C<0>) automatic draining of the pipe (default: |
|
|
525 | enabled). When automatic draining is enabled, then Async::Interrupt will |
|
|
526 | automatically clear the pipe. Otherwise the user is responsible for this |
|
|
527 | draining. |
|
|
528 | |
|
|
529 | This is useful when you want to share one pipe among many Async::Interrupt |
|
|
530 | objects. |
|
|
531 | |
|
|
532 | =item $async->pipe_drain |
|
|
533 | |
|
|
534 | Drains the pipe manually, for example, when autodrain is disabled. Does |
|
|
535 | nothing when no pipe is enabled. |
|
|
536 | |
|
|
537 | =item $async->post_fork |
|
|
538 | |
|
|
539 | The object will not normally be usable after a fork (as the pipe fd is |
|
|
540 | shared between processes). Calling this method after a fork in the child |
|
|
541 | ensures that the object will work as expected again. It only needs to be |
|
|
542 | called when the async object is used in the child. |
|
|
543 | |
|
|
544 | This only works when the pipe was created by Async::Interrupt. |
|
|
545 | |
|
|
546 | Async::Interrupt ensures that the reading file descriptor does not change |
|
|
547 | it's value. |
|
|
548 | |
|
|
549 | =item $signum = Async::Interrupt::sig2num $signame_or_number |
|
|
550 | |
|
|
551 | =item $signame = Async::Interrupt::sig2name $signame_or_number |
|
|
552 | |
|
|
553 | These two convenience functions simply convert a signal name or number to |
|
|
554 | the corresponding name or number. They are not used by this module and |
|
|
555 | exist just because perl doesn't have a nice way to do this on its own. |
|
|
556 | |
|
|
557 | They will return C<undef> on illegal names or numbers. |
|
|
558 | |
|
|
559 | =back |
|
|
560 | |
|
|
561 | =head1 THE Async::Interrupt::EventPipe CLASS |
|
|
562 | |
|
|
563 | Pipes are the predominant utility to make asynchronous signals |
|
|
564 | synchronous. However, pipes are hard to come by: they don't exist on the |
|
|
565 | broken windows platform, and on GNU/Linux systems, you might want to use |
|
|
566 | an C<eventfd> instead. |
|
|
567 | |
|
|
568 | This class creates selectable event pipes in a portable fashion: on |
|
|
569 | windows, it will try to create a tcp socket pair, on GNU/Linux, it will |
|
|
570 | try to create an eventfd and everywhere else it will try to use a normal |
|
|
571 | pipe. |
|
|
572 | |
|
|
573 | =over 4 |
|
|
574 | |
|
|
575 | =item $epipe = new Async::Interrupt::EventPipe |
|
|
576 | |
|
|
577 | This creates and returns an eventpipe object. This object is simply a |
|
|
578 | blessed array reference: |
|
|
579 | |
|
|
580 | =item ($r_fd, $w_fd) = $epipe->filenos |
|
|
581 | |
|
|
582 | Returns the read-side file descriptor and the write-side file descriptor. |
|
|
583 | |
|
|
584 | Example: pass an eventpipe object as pipe to the Async::Interrupt |
|
|
585 | constructor, and create an AnyEvent watcher for the read side. |
|
|
586 | |
|
|
587 | my $epipe = new Async::Interrupt::EventPipe; |
|
|
588 | my $asy = new Async::Interrupt pipe => [$epipe->filenos]; |
|
|
589 | my $iow = AnyEvent->io (fh => $epipe->fileno, poll => 'r', cb => sub { }); |
|
|
590 | |
|
|
591 | =item $r_fd = $epipe->fileno |
|
|
592 | |
|
|
593 | Return only the reading/listening side. |
|
|
594 | |
|
|
595 | =item $epipe->signal |
|
|
596 | |
|
|
597 | Write something to the pipe, in a portable fashion. |
|
|
598 | |
|
|
599 | =item $epipe->drain |
|
|
600 | |
|
|
601 | Drain (empty) the pipe. |
|
|
602 | |
|
|
603 | =item ($c_func, $c_arg) = $epipe->signal_func |
|
|
604 | |
|
|
605 | =item ($c_func, $c_arg) = $epipe->drain_func |
|
|
606 | |
|
|
607 | These two methods returns a function pointer and C<void *> argument |
|
|
608 | that can be called to have the effect of C<< $epipe->signal >> or C<< |
|
|
609 | $epipe->drain >>, respectively, on the XS level. |
|
|
610 | |
|
|
611 | They both have the following prototype and need to be passed their |
|
|
612 | C<$c_arg>, which is a C<void *> cast to an C<IV>: |
|
|
613 | |
|
|
614 | void (*c_func) (void *c_arg) |
|
|
615 | |
|
|
616 | An example call would look like: |
|
|
617 | |
|
|
618 | c_func (c_arg); |
|
|
619 | |
|
|
620 | =item $epipe->renew |
|
|
621 | |
|
|
622 | Recreates the pipe (useful after a fork). The reading side will not change |
|
|
623 | it's file descriptor number, but the writing side might. |
|
|
624 | |
|
|
625 | =item $epipe->wait |
|
|
626 | |
|
|
627 | This method blocks the process until there are events on the pipe. This is |
|
|
628 | not a very event-based or ncie way of usign an event pipe, but it can be |
|
|
629 | occasionally useful. |
|
|
630 | |
|
|
631 | =back |
218 | |
632 | |
219 | =cut |
633 | =cut |
220 | |
634 | |
221 | 1; |
635 | 1; |
222 | |
636 | |
223 | =back |
|
|
224 | |
|
|
225 | =head1 EXAMPLE |
|
|
226 | |
|
|
227 | There really should be a complete C/XS example. Bug me about it. |
|
|
228 | |
|
|
229 | =head1 IMPLEMENTATION DETAILS AND LIMITATIONS |
637 | =head1 IMPLEMENTATION DETAILS AND LIMITATIONS |
230 | |
638 | |
231 | This module works by "hijacking" SIGKILL, which is guaranteed to be always |
639 | This module works by "hijacking" SIGKILL, which is guaranteed to always |
232 | available in perl, but also cannot be caught, so is always available. |
640 | exist, but also cannot be caught, so is always available. |
233 | |
641 | |
234 | Basically, this module fakes the receive of a SIGKILL signal and |
642 | Basically, this module fakes the occurance of a SIGKILL signal and |
235 | then catches it. This makes normal signal handling slower (probably |
643 | then intercepts the interpreter handling it. This makes normal signal |
236 | unmeasurably), but has the advantage of not requiring a special runops nor |
644 | handling slower (probably unmeasurably, though), but has the advantage |
237 | slowing down normal perl execution a bit. |
645 | of not requiring a special runops function, nor slowing down normal perl |
|
|
646 | execution a bit. |
238 | |
647 | |
239 | It assumes that C<sig_atomic_t> and C<int> are both exception-safe to |
648 | It assumes that C<sig_atomic_t>, C<int> and C<IV> are all async-safe to |
240 | modify (C<sig_atomic_> is used by this module, and perl itself uses |
649 | modify. |
241 | C<int>, so we can assume that this is quite portable, at least w.r.t. |
|
|
242 | signals). |
|
|
243 | |
650 | |
244 | =head1 AUTHOR |
651 | =head1 AUTHOR |
245 | |
652 | |
246 | Marc Lehmann <schmorp@schmorp.de> |
653 | Marc Lehmann <schmorp@schmorp.de> |
247 | http://home.schmorp.de/ |
654 | http://home.schmorp.de/ |