… | |
… | |
101 | BEGIN { |
101 | BEGIN { |
102 | # the next line forces initialisation of internal |
102 | # the next line forces initialisation of internal |
103 | # signal handling # variables |
103 | # signal handling # variables |
104 | $SIG{KILL} = sub { }; |
104 | $SIG{KILL} = sub { }; |
105 | |
105 | |
106 | our $VERSION = '0.042'; |
106 | our $VERSION = '0.501'; |
107 | |
107 | |
108 | require XSLoader; |
108 | require XSLoader; |
109 | XSLoader::load ("Async::Interrupt", $VERSION); |
109 | XSLoader::load ("Async::Interrupt", $VERSION); |
110 | } |
110 | } |
111 | |
111 | |
… | |
… | |
157 | might use (the exception is C<errno>, which is saved and restored by |
157 | might use (the exception is C<errno>, which is saved and restored by |
158 | 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, |
159 | 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 |
160 | which case the requirements set out for C<cb> apply as well). |
160 | which case the requirements set out for C<cb> apply as well). |
161 | |
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 | |
162 | =item signal => $signame_or_value |
174 | =item signal => $signame_or_value |
163 | |
175 | |
164 | When this parameter is specified, then the Async::Interrupt will hook the |
176 | When this parameter is specified, then the Async::Interrupt will hook the |
165 | given signal, that is, it will effectively call C<< ->signal (0) >> each time |
177 | given signal, that is, it will effectively call C<< ->signal (0) >> each time |
166 | the given signal is caught by the process. |
178 | the given signal is caught by the process. |
… | |
… | |
175 | 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 |
176 | 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 |
177 | 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 |
178 | mode. |
190 | mode. |
179 | |
191 | |
180 | You can get a portable pipe and set non-blocking mode portably by using |
|
|
181 | e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution. |
|
|
182 | |
|
|
183 | It is also possible to pass in a linux eventfd as both read and write |
|
|
184 | handle (which is faster than a pipe). |
|
|
185 | |
|
|
186 | The object will keep a reference to the file handles. |
192 | The object will keep a reference to the file handles. |
187 | |
193 | |
188 | 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 |
189 | frameworks as well. |
195 | frameworks as well. |
190 | |
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 | |
191 | =back |
201 | =back |
192 | |
202 | |
193 | =cut |
203 | =cut |
194 | |
204 | |
195 | sub new { |
205 | sub new { |
196 | my ($class, %arg) = @_; |
206 | my ($class, %arg) = @_; |
197 | |
207 | |
198 | bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}), $class |
208 | bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class |
199 | } |
209 | } |
200 | |
210 | |
201 | =item ($signal_func, $signal_arg) = $async->signal_func |
211 | =item ($signal_func, $signal_arg) = $async->signal_func |
202 | |
212 | |
203 | 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 |
… | |
… | |
211 | signal_func (signal_arg, 0); |
221 | signal_func (signal_arg, 0); |
212 | |
222 | |
213 | 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 |
214 | 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. |
215 | |
225 | |
216 | 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> |
217 | portable). |
227 | (1..127 is portable). |
218 | |
228 | |
219 | 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 |
220 | signaled but before the callbacks are being executed, then the stored |
230 | signaled but before the callbacks are being executed, then the stored |
221 | 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 |
222 | 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 |
223 | invocations of the callback. |
233 | invocations of the callback. |
224 | |
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 | |
225 | =item $async->signal ($value=0) |
260 | =item $async->signal ($value=1) |
226 | |
261 | |
227 | 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 |
228 | will instantly trigger the callback invocation. |
263 | will instantly trigger the callback invocation. |
229 | |
264 | |
230 | 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> |
231 | portable). |
266 | (1..127 is portable). |
232 | |
267 | |
233 | =item $async->block |
268 | =item $async->block |
234 | |
269 | |
235 | =item $async->unblock |
270 | =item $async->unblock |
236 | |
271 | |
… | |
… | |
262 | enabled). Writing to a pipe is relatively expensive, so it can be disabled |
297 | enabled). Writing to a pipe is relatively expensive, so it can be disabled |
263 | when you know you are not waiting for it (for example, with L<EV> you |
298 | when you know you are not waiting for it (for example, with L<EV> you |
264 | could disable the pipe in a check watcher, and enable it in a prepare |
299 | could disable the pipe in a check watcher, and enable it in a prepare |
265 | watcher). |
300 | watcher). |
266 | |
301 | |
267 | Note that when C<fd_disable> is in effect, no attempt to read from the |
302 | Note that currently, while C<pipe_disable> is in effect, no attempt to |
268 | pipe will be done. |
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. |
269 | |
327 | |
270 | =cut |
328 | =cut |
271 | |
329 | |
272 | 1; |
330 | 1; |
273 | |
331 | |
… | |
… | |
287 | then intercepts the interpreter handling it. This makes normal signal |
345 | then intercepts the interpreter handling it. This makes normal signal |
288 | handling slower (probably unmeasurably, though), but has the advantage |
346 | handling slower (probably unmeasurably, though), but has the advantage |
289 | of not requiring a special runops function, nor slowing down normal perl |
347 | of not requiring a special runops function, nor slowing down normal perl |
290 | execution a bit. |
348 | execution a bit. |
291 | |
349 | |
292 | It assumes that C<sig_atomic_t> and C<int> are both async-safe to modify |
350 | It assumes that C<sig_atomic_t>, C<int> and C<IV> are all async-safe to |
293 | (C<sig_atomic_> is used by this module, and perl itself uses C<int>, so we |
351 | modify. |
294 | can assume that this is quite portable, at least w.r.t. signals). |
|
|
295 | |
352 | |
296 | =head1 AUTHOR |
353 | =head1 AUTHOR |
297 | |
354 | |
298 | Marc Lehmann <schmorp@schmorp.de> |
355 | Marc Lehmann <schmorp@schmorp.de> |
299 | http://home.schmorp.de/ |
356 | http://home.schmorp.de/ |