--- Async-Interrupt/Interrupt.pm 2009/07/14 19:29:26 1.11 +++ Async-Interrupt/Interrupt.pm 2009/07/30 03:59:47 1.21 @@ -55,6 +55,9 @@ to interrupt background processes regularly to send map updates to game clients. +Or L uses an interrupt object to wake up perl when new +events have arrived. + L and L could also use this to speed up result reporting. =item Speedy event loop invocation @@ -90,6 +93,137 @@ L or L). This, of course, incurs the overhead of a C and C syscall. +=head1 USAGE EXAMPLES + +=head2 Implementing race-free signal handling + +This example uses a single event pipe for all signals, and one +Async::Interrupt per signal. This code is actually what the L +module uses itself when Async::Interrupt is available. + +First, create the event pipe and hook it into the event loop + + $SIGPIPE = new Async::Interrupt::EventPipe; + $SIGPIPE_W = AnyEvent->io ( + fh => $SIGPIPE->fileno, + poll => "r", + cb => \&_signal_check, # defined later + ); + +Then, for each signal to hook, create an Async::Interrupt object. The +callback just sets a global variable, as we are only interested in +synchronous signals (i.e. when the event loop polls), which is why the +pipe draining is not done automatically. + + my $interrupt = new Async::Interrupt + cb => sub { undef $SIGNAL_RECEIVED{$signum} } + signal => $signum, + pipe => [$SIGPIPE->filenos], + pipe_autodrain => 0, + ; + +Finally, the I/O callback for the event pipe handles the signals: + + sub _signal_check { + # drain the pipe first + $SIGPIPE->drain; + + # two loops, just to be sure + while (%SIGNAL_RECEIVED) { + for (keys %SIGNAL_RECEIVED) { + delete $SIGNAL_RECEIVED{$_}; + warn "signal $_ received\n"; + } + } + } + +=head2 Interrupt perl from another thread + +This example interrupts the Perl interpreter from another thread, via the +XS API. This is used by e.g. the L module. + +On the Perl level, a new loop object (which contains the thread) +is created, by first calling some XS constructor, querying the +C-level callback function and feeding that as the C into the +Async::Interrupt constructor: + + my $self = XS_thread_constructor; + my ($c_func, $c_arg) = _c_func $self; # return the c callback + my $asy = new Async::Interrupt c_cb => [$c_func, $c_arg]; + +Then the newly created Interrupt object is queried for the signaling +function that the newly created thread should call, and this is in turn +told to the thread object: + + _attach $self, $asy->signal_func; + +So to repeat: first the XS object is created, then it is queried for the +callback that should be called when the Interrupt object gets signalled. + +Then the interrupt object is queried for the callback fucntion that the +thread should call to signal the Interrupt object, and this callback is +then attached to the thread. + +You have to be careful that your new thread is not signalling before the +signal function was configured, for example by starting the background +thread only within C<_attach>. + +That concludes the Perl part. + +The XS part consists of the actual constructor which creates a thread, +which is not relevant for this example, and two functions, C<_c_func>, +which returns the Perl-side callback, and C<_attach>, which configures +the signalling functioon that is safe toc all from another thread. For +simplicity, we will use global variables to store the functions, normally +you would somehow attach them to C<$self>. + +The C simply returns the address of a static function and arranges +for the object pointed to by C<$self> to be passed to it, as an integer: + + void + _c_func (SV *loop) + PPCODE: + EXTEND (SP, 2); + PUSHs (sv_2mortal (newSViv (PTR2IV (c_func)))); + PUSHs (sv_2mortal (newSViv (SvRV (loop)))); + +This would be the callback (since it runs in a normal Perl context, it is +permissible to manipulate Perl values): + + static void + c_func (pTHX_ void *loop_, int value) + { + SV *loop_object = (SV *)loop_; + ... + } + +And this attaches the signalling callback: + + static void (*my_sig_func) (void *signal_arg, int value); + static void *my_sig_arg; + + void + _attach (SV *loop_, IV sig_func, void *sig_arg) + CODE: + { + my_sig_func = sig_func; + my_sig_arg = sig_arg; + + /* now run the thread */ + thread_create (&u->tid, l_run, 0); + } + +And C (the background thread) would eventually call the signaling +function: + + my_sig_func (my_sig_arg, 0); + +You can have a look at L for an actual example using +intra-thread communication, locking and so on. + + +=head1 THE Async::Interrupt CLASS + =over 4 =cut @@ -100,10 +234,11 @@ BEGIN { # the next line forces initialisation of internal - # signal handling # variables + # signal handling variables, otherwise, PL_sig_pending + # etc. will be null pointers. $SIG{KILL} = sub { }; - our $VERSION = '0.041'; + our $VERSION = '1.0'; require XSLoader; XSLoader::load ("Async::Interrupt", $VERSION); @@ -136,7 +271,7 @@ If the callback should throw an exception, then it will be caught, and C<$Async::Interrupt::DIED> will be called with C<$@> containing -the exception. The default will simply C about the message and +the exception. The default will simply C about the message and continue. =item c_cb => [$c_func, $c_arg] @@ -159,6 +294,18 @@ so you can call any perl functions and modify any perl data structures (in which case the requirements set out for C apply as well). +=item var => $scalar_ref + +When specified, then the given argument must be a reference to a +scalar. The scalar will be set to C<0> initially. Signalling the interrupt +object will set it to the passed value, handling the interrupt will reset +it to C<0> again. + +Note that the only thing you are legally allowed to do is to is to check +the variable in a boolean or integer context (e.g. comparing it with a +string, or printing it, will I it and might cause your program to +crash or worse). + =item signal => $signame_or_value When this parameter is specified, then the Async::Interrupt will hook the @@ -168,6 +315,11 @@ Only one async can hook a given signal, and the signal will be restored to defaults when the Async::Interrupt object gets destroyed. +=item signal_hysteresis => $boolean + +Sets the initial signal hysteresis state, see the C +method, below. + =item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] Specifies two file descriptors (or file handles) that should be signalled @@ -177,17 +329,23 @@ are written. It is required that the file handles are both in nonblocking mode. -You can get a portable pipe and set non-blocking mode portably by using -e.g. L from the L distribution. - -It is also possible to pass in a linux eventfd as both read and write -handle (which is faster than a pipe). - The object will keep a reference to the file handles. This can be used to ensure that async notifications will interrupt event frameworks as well. +Note that C will create a suitable signal fd +automatically when your program requests one, so you don't have to specify +this argument when all you want is an extra file descriptor to watch. + +If you want to share a single event pipe between multiple Async::Interrupt +objects, you can use the C class to manage +those. + +=item pipe_autodrain => $boolean + +Sets the initial autodrain state, see the C method, below. + =back =cut @@ -195,14 +353,21 @@ sub new { my ($class, %arg) = @_; - bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}), $class + my $self = bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class; + + # urgs, reminds me of Event + for my $attr (qw(pipe_autodrain signal_hysteresis)) { + $self->$attr ($arg{$attr}) if exists $arg{$attr}; + } + + $self } =item ($signal_func, $signal_arg) = $async->signal_func -Returns the address of a function to call asynchronously. The function has -the following prototype and needs to be passed the specified C<$c_arg>, -which is a C cast to C: +Returns the address of a function to call asynchronously. The function +has the following prototype and needs to be passed the specified +C<$signal_arg>, which is a C cast to C: void (*signal_func) (void *signal_arg, int value) @@ -213,8 +378,8 @@ The function is safe to call from within signal and thread contexts, at any time. The specified C is passed to both C and Perl callback. -C<$value> must be in the valid range for a C (0..127 is -portable). +C<$value> must be in the valid range for a C, except C<0> +(1..127 is portable). If the function is called while the Async::Interrupt object is already signaled but before the callbacks are being executed, then the stored @@ -222,13 +387,55 @@ nature of the code, the C can even be passed to two consecutive invocations of the callback. -=item $async->signal ($value=0) +=item $address = $async->c_var + +Returns the address (cast to IV) of an C variable. The variable is set +to C<0> initially and gets set to the passed value whenever the object +gets signalled, and reset to C<0> once the interrupt has been handled. + +Note that it is often beneficial to just call C to +handle any interrupts. + +Example: call some XS function to store the address, then show C code +waiting for it. + + my_xs_func $async->c_var; + + static IV *valuep; + + void + my_xs_func (void *addr) + CODE: + valuep = (IV *)addr; + + // code in a loop, waiting + while (!*valuep) + ; // do something + +=item $async->signal ($value=1) This signals the given async object from Perl code. Semi-obviously, this -will instantly trigger the callback invocation. +will instantly trigger the callback invocation (it does not, as the name +might imply, do anything with POSIX signals). -C<$value> must be in the valid range for a C (0..127 is -portable). +C<$value> must be in the valid range for a C, except C<0> +(1..127 is portable). + +=item $async->signal_hysteresis ($enable) + +Enables or disables signal hysteresis (default: disabled). If a POSIX +signal is used as a signal source for the interrupt object, then enabling +signal hysteresis causes Async::Interrupt to reset the signal action to +C in the signal handler and restore it just before handling the +interruption. + +When you expect a lot of signals (e.g. when using SIGIO), then enabling +signal hysteresis can reduce the number of handler invocations +considerably, at the cost of two extra syscalls. + +Note that setting the signal to C can have unintended side +effects when you fork and exec other programs, as often they do nto expect +signals to be ignored by default. =item $async->block @@ -254,6 +461,23 @@ This is the recommended (and fastest) way to implement critical sections. +=item ($block_func, $block_arg) = $async->scope_block_func + +Returns the address of a function that implements the C +functionality. + +It has the following prototype and needs to be passed the specified +C<$block_arg>, which is a C cast to C: + + void (*block_func) (void *block_arg) + +An example call would look like: + + block_func (block_arg); + +The function is safe to call only from within the toplevel of a perl XS +function and will call C and C (in this order!). + =item $async->pipe_enable =item $async->pipe_disable @@ -264,19 +488,126 @@ could disable the pipe in a check watcher, and enable it in a prepare watcher). -Note that when C is in effect, no attempt to read from the -pipe will be done. +Note that currently, while C is in effect, no attempt to +read from the pipe will be done when handling events. This might change as +soon as I realize why this is a mistake. -=cut +=item $fileno = $async->pipe_fileno -1; +Returns the reading side of the signalling pipe. If no signalling pipe is +currently attached to the object, it will dynamically create one. + +Note that the only valid oepration on this file descriptor is to wait +until it is readable. The fd might belong currently to a pipe, a tcp +socket, or an eventfd, depending on the platform, and is guaranteed to be +C