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.3 by root, Thu Jul 2 16:12:40 2009 UTC vs.
Revision 1.4 by root, Thu Jul 2 16:15:52 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
… …
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).
109 110
110=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing] 111=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
111 112
112Specifies two file descriptors (or file handles) that should be signalled 113Specifies two file descriptors (or file handles) that should be signalled
113whenever the async interrupt is signalled. This means a single octet will 114whenever the async interrupt is signalled. This means a single octet will
… …
115read again. Due to races, it is unlikely but possible that multiple octets 116read 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 117are written. It is required that the file handles are both in nonblocking
117mode. 118mode.
118 119
119(You can get a portable pipe and set non-blocking mode portably by using 120(You can get a portable pipe and set non-blocking mode portably by using
120e.g. L<AnyEvent::Util> from the L<AnyEvent> distro). 121e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution).
121 122
122The object will keep a reference to the file handles. 123The object will keep a reference to the file handles.
123 124
124This can be used to ensure that async notifications will interrupt event 125This can be used to ensure that async notifications will interrupt event
125frameworks as well. 126frameworks as well.
… …
173Sometimes you need a "critical section" of code that will not be 174Sometimes you need a "critical section" of code that will not be
174interrupted by an Async::Interrupt. This can be implemented by calling C<< 175interrupted by an Async::Interrupt. This can be implemented by calling C<<
175$async->block >> before the critical section, and C<< $async->unblock >> 176$async->block >> before the critical section, and C<< $async->unblock >>
176afterwards. 177afterwards.
177 178
178Note that there must be exactly one call of C<unblock> for ever<y previous 179Note that there must be exactly one call of C<unblock> for every previous
179call to C<block> (i.e. calls can nest). 180call to C<block> (i.e. calls can nest).
180 181
181Since ensuring this in the presense of exceptions and threads is 182Since ensuring this in the presence of exceptions and threads is
182usually more difficult than you imagine, I recommend using C<< 183usually more difficult than you imagine, I recommend using C<<
183$async->scoped_block >> instead. 184$async->scoped_block >> instead.
184 185
185=item $async->scope_block 186=item $async->scope_block
186 187
… …
196 197
197=back 198=back
198 199
199=head1 EXAMPLE 200=head1 EXAMPLE
200 201
201#TODO 202There really should be a complete C/XS example. Bug me about it.
202 203
203=head1 IMPLEMENTATION DETAILS AND LIMITATIONS 204=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
204 205
205This module works by "hijacking" SIGKILL, which is guarenteed to be always 206This module works by "hijacking" SIGKILL, which is guaranteed to be always
206available in perl, but also cannot be caught, so is always available. 207available in perl, but also cannot be caught, so is always available.
207 208
208Basically, this module fakes the receive of a SIGKILL signal and 209Basically, this module fakes the receive of a SIGKILL signal and
209then catches it. This makes normal signal handling slower (probably 210then catches it. This makes normal signal handling slower (probably
210unmeasurably), but has the advantage of not requiring a special runops nor 211unmeasurably), but has the advantage of not requiring a special runops nor
211slowing down normal perl execution a bit. 212slowing down normal perl execution a bit.
212 213
213It assumes that C<sig_atomic_t> and C<int> are both exception-safe to 214It 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 215modify (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. 216C<int>, so we can assume that this is quite portable, at least w.r.t.
216signals). 217signals).
217 218
218=head1 AUTHOR 219=head1 AUTHOR
219 220
220 Marc Lehmann <schmorp@schmorp.de> 221 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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