… | |
… | |
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 | and then signal the perl interpreter on certain events. One common way is |
17 | to write some data to a pipe and use an event handling toolkit to watch |
17 | to write some data to a pipe and use an event handling toolkit to watch |
… | |
… | |
37 | function also takes an integer argument in the range SIG_ATOMIC_MIN to |
37 | function also takes an integer argument in the range SIG_ATOMIC_MIN to |
38 | SIG_ATOMIC_MAX (guaranteed to allow at least 0..127). |
38 | SIG_ATOMIC_MAX (guaranteed to allow at least 0..127). |
39 | |
39 | |
40 | Since this kind of interruption is fast, but can only interrupt a |
40 | Since this kind of interruption is fast, but can only interrupt a |
41 | I<running> interpreter, there is optional support for also signalling a |
41 | I<running> interpreter, there is optional support for also signalling a |
42 | pipe - that means you can also wait for the pipe to become readable while |
42 | pipe - that means you can also wait for the pipe to become readable (e.g. |
43 | #TODO# |
43 | via L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a |
|
|
44 | C<read> and C<write> syscall. |
44 | |
45 | |
45 | =over 4 |
46 | =over 4 |
46 | |
47 | |
47 | =cut |
48 | =cut |
48 | |
49 | |
… | |
… | |
100 | C<$value> is the C<value> passed to some earlier call to either C<$signal> |
101 | C<$value> is the C<value> passed to some earlier call to either C<$signal> |
101 | or the C<signal_func> function. |
102 | or the C<signal_func> function. |
102 | |
103 | |
103 | Note that, because the callback can be invoked at almost any time, you |
104 | Note that, because the callback can be invoked at almost any time, you |
104 | have to be careful at saving and restoring global variables that Perl |
105 | have to be careful at saving and restoring global variables that Perl |
105 | might use (the excetpion is C<errno>, which is aved and restored by |
106 | might use (the exception is C<errno>, which is saved and restored by |
106 | Async::Interrupt). The callback itself runs as part of the perl context, |
107 | Async::Interrupt). The callback itself runs as part of the perl context, |
107 | so you can call any perl functions and modify any perl data structures (in |
108 | so you can call any perl functions and modify any perl data structures (in |
108 | which case the requireemnts set out for C<cb> apply as well). |
109 | which case the requirements set out for C<cb> apply as well). |
109 | |
110 | |
110 | =item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] |
111 | =item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] |
111 | |
112 | |
112 | Specifies two file descriptors (or file handles) that should be signalled |
113 | Specifies two file descriptors (or file handles) that should be signalled |
113 | whenever the async interrupt is signalled. This means a single octet will |
114 | whenever the async interrupt is signalled. This means a single octet will |
… | |
… | |
115 | read again. Due to races, it is unlikely but possible that multiple octets |
116 | read again. Due to races, it is unlikely but possible that multiple octets |
116 | are written. It is required that the file handles are both in nonblocking |
117 | are written. It is required that the file handles are both in nonblocking |
117 | mode. |
118 | mode. |
118 | |
119 | |
119 | (You can get a portable pipe and set non-blocking mode portably by using |
120 | (You can get a portable pipe and set non-blocking mode portably by using |
120 | e.g. L<AnyEvent::Util> from the L<AnyEvent> distro). |
121 | e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution). |
121 | |
122 | |
122 | The object will keep a reference to the file handles. |
123 | The object will keep a reference to the file handles. |
123 | |
124 | |
124 | This can be used to ensure that async notifications will interrupt event |
125 | This can be used to ensure that async notifications will interrupt event |
125 | frameworks as well. |
126 | frameworks as well. |
… | |
… | |
173 | Sometimes you need a "critical section" of code that will not be |
174 | Sometimes you need a "critical section" of code that will not be |
174 | interrupted by an Async::Interrupt. This can be implemented by calling C<< |
175 | interrupted by an Async::Interrupt. This can be implemented by calling C<< |
175 | $async->block >> before the critical section, and C<< $async->unblock >> |
176 | $async->block >> before the critical section, and C<< $async->unblock >> |
176 | afterwards. |
177 | afterwards. |
177 | |
178 | |
178 | Note that there must be exactly one call of C<unblock> for ever<y previous |
179 | Note that there must be exactly one call of C<unblock> for every previous |
179 | call to C<block> (i.e. calls can nest). |
180 | call to C<block> (i.e. calls can nest). |
180 | |
181 | |
181 | Since ensuring this in the presense of exceptions and threads is |
182 | Since ensuring this in the presence of exceptions and threads is |
182 | usually more difficult than you imagine, I recommend using C<< |
183 | usually more difficult than you imagine, I recommend using C<< |
183 | $async->scoped_block >> instead. |
184 | $async->scoped_block >> instead. |
184 | |
185 | |
185 | =item $async->scope_block |
186 | =item $async->scope_block |
186 | |
187 | |
… | |
… | |
196 | |
197 | |
197 | =back |
198 | =back |
198 | |
199 | |
199 | =head1 EXAMPLE |
200 | =head1 EXAMPLE |
200 | |
201 | |
201 | #TODO |
202 | There really should be a complete C/XS example. Bug me about it. |
202 | |
203 | |
203 | =head1 IMPLEMENTATION DETAILS AND LIMITATIONS |
204 | =head1 IMPLEMENTATION DETAILS AND LIMITATIONS |
204 | |
205 | |
205 | This module works by "hijacking" SIGKILL, which is guarenteed to be always |
206 | This module works by "hijacking" SIGKILL, which is guaranteed to be always |
206 | available in perl, but also cannot be caught, so is always available. |
207 | available in perl, but also cannot be caught, so is always available. |
207 | |
208 | |
208 | Basically, this module fakes the receive of a SIGKILL signal and |
209 | Basically, this module fakes the receive of a SIGKILL signal and |
209 | then catches it. This makes normal signal handling slower (probably |
210 | then catches it. This makes normal signal handling slower (probably |
210 | unmeasurably), but has the advantage of not requiring a special runops nor |
211 | unmeasurably), but has the advantage of not requiring a special runops nor |
211 | slowing down normal perl execution a bit. |
212 | slowing down normal perl execution a bit. |
212 | |
213 | |
213 | It assumes that C<sig_atomic_t> and C<int> are both exception-safe to |
214 | It assumes that C<sig_atomic_t> and C<int> are both exception-safe to |
214 | modify (C<sig_atomic_> is used by this module, and perl itself uses |
215 | modify (C<sig_atomic_> is used by this module, and perl itself uses |
215 | C<int>, so we can assume that this is quite portbale, at least w.r.t. |
216 | C<int>, so we can assume that this is quite portable, at least w.r.t. |
216 | signals). |
217 | signals). |
217 | |
218 | |
218 | =head1 AUTHOR |
219 | =head1 AUTHOR |
219 | |
220 | |
220 | Marc Lehmann <schmorp@schmorp.de> |
221 | Marc Lehmann <schmorp@schmorp.de> |