ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Async-Interrupt/Interrupt.pm
(Generate patch)

Comparing Async-Interrupt/Interrupt.pm (file contents):
Revision 1.16 by root, Fri Jul 17 21:02:18 2009 UTC vs.
Revision 1.17 by root, Tue Jul 28 01:19:44 2009 UTC

… …
53 53
54For example the deliantra game server uses a variant of this technique 54For example the deliantra game server uses a variant of this technique
55to interrupt background processes regularly to send map updates to game 55to interrupt background processes regularly to send map updates to game
56clients. 56clients.
57 57
58Or L<EV::Loop::Async> uses an interrupt object to wake up perl when new
59events have arrived.
60
58L<IO::AIO> and L<BDB> could also use this to speed up result reporting. 61L<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
62One could use this module e.g. in L<Coro> to interrupt a running coro-thread 65One could use this module e.g. in L<Coro> to interrupt a running coro-thread
… …
162which case the requirements set out for C<cb> apply as well). 165which case the requirements set out for C<cb> apply as well).
163 166
164=item var => $scalar_ref 167=item var => $scalar_ref
165 168
166When specified, then the given argument must be a reference to a 169When specified, then the given argument must be a reference to a
167scalar. The scalar will be set to C<0> intiially. Signalling the interrupt 170scalar. The scalar will be set to C<0> initially. Signalling the interrupt
168object will set it to the passed value, handling the interrupt will reset 171object will set it to the passed value, handling the interrupt will reset
169it to C<0> again. 172it to C<0> again.
170 173
171Note that the only thing you are legally allowed to do is to is to check 174Note that the only thing you are legally allowed to do is to is to check
172the variable in a boolean or integer context (e.g. comparing it with a 175the variable in a boolean or integer context (e.g. comparing it with a
… …
214 bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class 217 bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class
215} 218}
216 219
217=item ($signal_func, $signal_arg) = $async->signal_func 220=item ($signal_func, $signal_arg) = $async->signal_func
218 221
219Returns the address of a function to call asynchronously. The function has 222Returns the address of a function to call asynchronously. The function
220the following prototype and needs to be passed the specified C<$c_arg>, 223has the following prototype and needs to be passed the specified
221which is a C<void *> cast to C<IV>: 224C<$signal_arg>, which is a C<void *> cast to C<IV>:
222 225
223 void (*signal_func) (void *signal_arg, int value) 226 void (*signal_func) (void *signal_arg, int value)
224 227
225An example call would look like: 228An example call would look like:
226 229
… …
264 ; // do something 267 ; // do something
265 268
266=item $async->signal ($value=1) 269=item $async->signal ($value=1)
267 270
268This signals the given async object from Perl code. Semi-obviously, this 271This signals the given async object from Perl code. Semi-obviously, this
269will instantly trigger the callback invocation. 272will instantly trigger the callback invocation (it does not, as the name
273might imply, do anything with POSIX signals).
270 274
271C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0> 275C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
272(1..127 is portable). 276(1..127 is portable).
277
278=item $async->signal_hysteresis ($enable)
279
280Enables or disables signal hysteresis (default: disabled). If a POSIX
281signal is used as a signal source for the interrupt object, then enabling
282signal hysteresis causes Async::Interrupt to reset the signal action to
283C<SIG_IGN> in the signal handler and restore it just before handling the
284interruption.
285
286When you expect a lot of signals (e.g. when using SIGIO), then enabling
287signal hysteresis can reduce the number of handler invocations
288considerably, at the cost of two extra syscalls.
289
290Note that setting the signal to C<SIG_IGN> can have unintended side
291effects when you fork and exec other programs, as often they do nto expect
292signals to be ignored by default.
273 293
274=item $async->block 294=item $async->block
275 295
276=item $async->unblock 296=item $async->unblock
277 297
… …
292This call C<< $async->block >> and installs a handler that is called when 312This call C<< $async->block >> and installs a handler that is called when
293the current scope is exited (via an exception, by canceling the Coro 313the current scope is exited (via an exception, by canceling the Coro
294thread, by calling last/goto etc.). 314thread, by calling last/goto etc.).
295 315
296This is the recommended (and fastest) way to implement critical sections. 316This is the recommended (and fastest) way to implement critical sections.
317
318=item ($block_func, $block_arg) = $async->scope_block_func
319
320Returns the address of a function that implements the C<scope_block>
321functionality.
322
323It has the following prototype and needs to be passed the specified
324C<$block_arg>, which is a C<void *> cast to C<IV>:
325
326 void (*block_func) (void *block_arg)
327
328An example call would look like:
329
330 block_func (block_arg);
331
332The function is safe to call only from within the toplevel of a perl XS
333function and will call C<LEAVE> and C<ENTER> (in this order!).
297 334
298=item $async->pipe_enable 335=item $async->pipe_enable
299 336
300=item $async->pipe_disable 337=item $async->pipe_disable
301 338

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines