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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.3 by root, Thu Jul 2 16:12:40 2009 UTC vs.
Revision 1.6 by root, Sat Jul 11 22:16:50 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.
43#TODO# 43via L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a
44C<read> and C<write> syscall.
44 45
45=over 4 46=over 4
46 47
47=cut 48=cut
48 49
49package Async::Interrupt; 50package Async::Interrupt;
50 51
51no warnings; 52no warnings;
52 53
53BEGIN { 54BEGIN {
54 $VERSION = '0.02'; 55 $VERSION = '0.03';
55 56
56 require XSLoader; 57 require XSLoader;
57 XSLoader::load Async::Interrupt::, $VERSION; 58 XSLoader::load Async::Interrupt::, $VERSION;
58} 59}
59 60
… …
100C<$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>
101or the C<signal_func> function. 102or the C<signal_func> function.
102 103
103Note 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
104have to be careful at saving and restoring global variables that Perl 105have to be careful at saving and restoring global variables that Perl
105might 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
106Async::Interrupt). The callback itself runs as part of the perl context, 107Async::Interrupt). The callback itself runs as part of the perl context,
107so 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
108which 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.
109 119
110=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]
111 121
112Specifies two file descriptors (or file handles) that should be signalled 122Specifies two file descriptors (or file handles) that should be signalled
113whenever the async interrupt is signalled. This means a single octet will 123whenever the async interrupt is signalled. This means a single octet will
114be 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
115read 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
116are 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
117mode. 127mode.
118 128
119(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
120e.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).
121 134
122The object will keep a reference to the file handles. 135The object will keep a reference to the file handles.
123 136
124This can be used to ensure that async notifications will interrupt event 137This can be used to ensure that async notifications will interrupt event
125frameworks as well. 138frameworks as well.
… …
129=cut 142=cut
130 143
131sub new { 144sub new {
132 my ($class, %arg) = @_; 145 my ($class, %arg) = @_;
133 146
134 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
135} 148}
136 149
137=item ($signal_func, $signal_arg) = $async->signal_func 150=item ($signal_func, $signal_arg) = $async->signal_func
138 151
139Returns the address of a function to call asynchronously. The function has 152Returns the address of a function to call asynchronously. The function has
… …
173Sometimes you need a "critical section" of code that will not be 186Sometimes you need a "critical section" of code that will not be
174interrupted by an Async::Interrupt. This can be implemented by calling C<< 187interrupted by an Async::Interrupt. This can be implemented by calling C<<
175$async->block >> before the critical section, and C<< $async->unblock >> 188$async->block >> before the critical section, and C<< $async->unblock >>
176afterwards. 189afterwards.
177 190
178Note that there must be exactly one call of C<unblock> for ever<y previous 191Note that there must be exactly one call of C<unblock> for every previous
179call to C<block> (i.e. calls can nest). 192call to C<block> (i.e. calls can nest).
180 193
181Since ensuring this in the presense of exceptions and threads is 194Since ensuring this in the presence of exceptions and threads is
182usually more difficult than you imagine, I recommend using C<< 195usually more difficult than you imagine, I recommend using C<<
183$async->scoped_block >> instead. 196$async->scoped_block >> instead.
184 197
185=item $async->scope_block 198=item $async->scope_block
186 199
… …
188the current scope is exited (via an exception, by canceling the Coro 201the current scope is exited (via an exception, by canceling the Coro
189thread, by calling last/goto etc.). 202thread, by calling last/goto etc.).
190 203
191This is the recommended (and fastest) way to implement critical sections. 204This is the recommended (and fastest) way to implement critical sections.
192 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
193=cut 219=cut
194 220
1951; 2211;
196 222
197=back 223=back
198 224
199=head1 EXAMPLE 225=head1 EXAMPLE
200 226
201#TODO 227There really should be a complete C/XS example. Bug me about it.
202 228
203=head1 IMPLEMENTATION DETAILS AND LIMITATIONS 229=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
204 230
205This module works by "hijacking" SIGKILL, which is guarenteed to be always 231This module works by "hijacking" SIGKILL, which is guaranteed to be always
206available in perl, but also cannot be caught, so is always available. 232available in perl, but also cannot be caught, so is always available.
207 233
208Basically, this module fakes the receive of a SIGKILL signal and 234Basically, this module fakes the receive of a SIGKILL signal and
209then catches it. This makes normal signal handling slower (probably 235then catches it. This makes normal signal handling slower (probably
210unmeasurably), but has the advantage of not requiring a special runops nor 236unmeasurably), but has the advantage of not requiring a special runops nor
211slowing down normal perl execution a bit. 237slowing down normal perl execution a bit.
212 238
213It 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
214modify (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
215C<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.
216signals). 242signals).
217 243
218=head1 AUTHOR 244=head1 AUTHOR
219 245
220 Marc Lehmann <schmorp@schmorp.de> 246 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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