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.2 by root, Thu Jul 2 15:13:03 2009 UTC vs.
Revision 1.7 by root, Sat Jul 11 22:24:30 2009 UTC

… …
7 use Async::Interrupt; 7 use Async::Interrupt;
8 8
9=head1 DESCRIPTION 9=head1 DESCRIPTION
10 10
11This module implements a single feature only of interest to advanced perl 11This module implements a single feature only of interest to advanced perl
12modules, namely asynchronous interruptions (think "unix signals", which 12modules, namely asynchronous interruptions (think "UNIX signals", which
13are very similar). 13are very similar).
14 14
15Sometimes, modules wish to run code asynchronously (in another thread), 15Sometimes, modules wish to run code asynchronously (in another thread),
16and then signal the perl interpreter on certain events. One common way is 16and then signal the perl interpreter on certain events. One common way is
17to write some data to a pipe and use an event handling toolkit to watch 17to write some data to a pipe and use an event handling toolkit to watch
… …
37function also takes an integer argument in the range SIG_ATOMIC_MIN to 37function also takes an integer argument in the range SIG_ATOMIC_MIN to
38SIG_ATOMIC_MAX (guaranteed to allow at least 0..127). 38SIG_ATOMIC_MAX (guaranteed to allow at least 0..127).
39 39
40Since this kind of interruption is fast, but can only interrupt a 40Since this kind of interruption is fast, but can only interrupt a
41I<running> interpreter, there is optional support for also signalling a 41I<running> interpreter, there is optional support for also signalling a
42pipe - that means you can also wait for the pipe to become readable while 42pipe - that means you can also wait for the pipe to become readable (e.g.
43via L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a
44C<read> and C<write> syscall.
43 45
44=over 4 46=over 4
45 47
46=cut 48=cut
47 49
48package Async::Interrupt; 50package Async::Interrupt;
49 51
50no warnings; 52no warnings;
51 53
52BEGIN { 54BEGIN {
53 $VERSION = '0.02'; 55 $VERSION = '0.04';
54 56
55 require XSLoader; 57 require XSLoader;
56 XSLoader::load Async::Interrupt::, $VERSION; 58 XSLoader::load Async::Interrupt::, $VERSION;
57} 59}
58 60
… …
99C<$value> is the C<value> passed to some earlier call to either C<$signal> 101C<$value> is the C<value> passed to some earlier call to either C<$signal>
100or the C<signal_func> function. 102or the C<signal_func> function.
101 103
102Note that, because the callback can be invoked at almost any time, you 104Note that, because the callback can be invoked at almost any time, you
103have to be careful at saving and restoring global variables that Perl 105have to be careful at saving and restoring global variables that Perl
104might use (the excetpion is C<errno>, which is aved and restored by 106might use (the exception is C<errno>, which is saved and restored by
105Async::Interrupt). The callback itself runs as part of the perl context, 107Async::Interrupt). The callback itself runs as part of the perl context,
106so you can call any perl functions and modify any perl data structures (in 108so you can call any perl functions and modify any perl data structures (in
107which case the requireemnts set out for C<cb> apply as well). 109which case the requirements set out for C<cb> apply as well).
110
111=item signal => $signame_or_value
112
113When this parameter is specified, then the Async::Interrupt will hook the
114given signal, that is, it will effectively call C<< ->signal (0) >> each time
115the given signal is caught by the process.
116
117Only one async can hook a given signal, and the signal will be restored to
118defaults when the Async::Interrupt object gets destroyed.
108 119
109=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] 120=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
110 121
111Specifies two file descriptors (or file handles) that should be signalled 122Specifies two file descriptors (or file handles) that should be signalled
112whenever the async interrupt is signalled. This means a single octet will 123whenever the async interrupt is signalled. This means a single octet will
113be written to it, and before the callback is being invoked, it will be 124be written to it, and before the callback is being invoked, it will be
114read again. Due to races, it is unlikely but possible that multiple octets 125read again. Due to races, it is unlikely but possible that multiple octets
115are written. It is required that the file handles are both in nonblocking 126are written. It is required that the file handles are both in nonblocking
116mode. 127mode.
117 128
118(You can get a portable pipe and set non-blocking mode portably by using 129You can get a portable pipe and set non-blocking mode portably by using
119e.g. L<AnyEvent::Util> from the L<AnyEvent> distro). 130e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution.
131
132It is also possible to pass in a linux eventfd as both read and write
133handle (which is faster than a pipe).
120 134
121The object will keep a reference to the file handles. 135The object will keep a reference to the file handles.
122 136
123This can be used to ensure that async notifications will interrupt event 137This can be used to ensure that async notifications will interrupt event
124frameworks as well. 138frameworks as well.
… …
128=cut 142=cut
129 143
130sub new { 144sub new {
131 my ($class, %arg) = @_; 145 my ($class, %arg) = @_;
132 146
133 bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1]), $class 147 bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}), $class
134} 148}
135 149
136=item ($signal_func, $signal_arg) = $async->signal_func 150=item ($signal_func, $signal_arg) = $async->signal_func
137 151
138Returns the address of a function to call asynchronously. The function has 152Returns the address of a function to call asynchronously. The function has
… …
165C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is 179C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is
166portable). 180portable).
167 181
168=item $async->block 182=item $async->block
169 183
170Sometimes you need a "critical section" of code where
171
172=item $async->unblock 184=item $async->unblock
173 185
186Sometimes you need a "critical section" of code that will not be
187interrupted by an Async::Interrupt. This can be implemented by calling C<<
188$async->block >> before the critical section, and C<< $async->unblock >>
189afterwards.
190
191Note that there must be exactly one call of C<unblock> for every previous
192call to C<block> (i.e. calls can nest).
193
194Since ensuring this in the presence of exceptions and threads is
195usually more difficult than you imagine, I recommend using C<<
196$async->scoped_block >> instead.
197
198=item $async->scope_block
199
200This call C<< $async->block >> and installs a handler that is called when
201the current scope is exited (via an exception, by canceling the Coro
202thread, by calling last/goto etc.).
203
204This is the recommended (and fastest) way to implement critical sections.
205
206=item $async->pipe_enable
207
208=item $async->pipe_disable
209
210Enable/disable signalling the pipe when the interrupt occurs (default is
211enabled). Writing to a pipe is relatively expensive, so it can be disabled
212when you know you are not waiting for it (for example, with L<EV> you
213could disable the pipe in a check watcher, and enable it in a prepare
214watcher).
215
216Note that when C<fd_disable> is in effect, no attempt to read from the
217pipe will be done.
218
174=cut 219=cut
175 220
1761; 2211;
177 222
178=back 223=back
179 224
180=head1 EXAMPLE 225=head1 EXAMPLE
181 226
182#TODO 227There really should be a complete C/XS example. Bug me about it.
183 228
184=head1 IMPLEMENTATION DETAILS AND LIMITATIONS 229=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
185 230
186This module works by "hijacking" SIGKILL, which is guarenteed to be always 231This module works by "hijacking" SIGKILL, which is guaranteed to be always
187available in perl, but also cannot be caught, so is always available. 232available in perl, but also cannot be caught, so is always available.
188 233
189Basically, this module fakes the receive of a SIGKILL signal and 234Basically, this module fakes the receive of a SIGKILL signal and
190then catches it. This makes normal signal handling slower (probably 235then catches it. This makes normal signal handling slower (probably
191unmeasurably), but has the advantage of not requiring a special runops nor 236unmeasurably), but has the advantage of not requiring a special runops nor
192slowing down normal perl execution a bit. 237slowing down normal perl execution a bit.
193 238
194It assumes that C<sig_atomic_t> and C<int> are both exception-safe to 239It assumes that C<sig_atomic_t> and C<int> are both exception-safe to
195modify (C<sig_atomic_> is used by this module, and perl itself uses 240modify (C<sig_atomic_> is used by this module, and perl itself uses
196C<int>, so we can assume that this is quite portbale, at least w.r.t. 241C<int>, so we can assume that this is quite portable, at least w.r.t.
197signals). 242signals).
198 243
199=head1 AUTHOR 244=head1 AUTHOR
200 245
201 Marc Lehmann <schmorp@schmorp.de> 246 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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