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.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.
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
… …
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).
108 110
109=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]
110 112
111Specifies two file descriptors (or file handles) that should be signalled 113Specifies two file descriptors (or file handles) that should be signalled
112whenever the async interrupt is signalled. This means a single octet will 114whenever the async interrupt is signalled. This means a single octet will
… …
114read 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
115are 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
116mode. 118mode.
117 119
118(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
119e.g. L<AnyEvent::Util> from the L<AnyEvent> distro). 121e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution).
120 122
121The object will keep a reference to the file handles. 123The object will keep a reference to the file handles.
122 124
123This can be used to ensure that async notifications will interrupt event 125This can be used to ensure that async notifications will interrupt event
124frameworks as well. 126frameworks as well.
… …
165C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is 167C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is
166portable). 168portable).
167 169
168=item $async->block 170=item $async->block
169 171
170Sometimes you need a "critical section" of code where
171
172=item $async->unblock 172=item $async->unblock
173 173
174Sometimes you need a "critical section" of code that will not be
175interrupted by an Async::Interrupt. This can be implemented by calling C<<
176$async->block >> before the critical section, and C<< $async->unblock >>
177afterwards.
178
179Note that there must be exactly one call of C<unblock> for every previous
180call to C<block> (i.e. calls can nest).
181
182Since ensuring this in the presence of exceptions and threads is
183usually more difficult than you imagine, I recommend using C<<
184$async->scoped_block >> instead.
185
186=item $async->scope_block
187
188This call C<< $async->block >> and installs a handler that is called when
189the current scope is exited (via an exception, by canceling the Coro
190thread, by calling last/goto etc.).
191
192This is the recommended (and fastest) way to implement critical sections.
193
174=cut 194=cut
175 195
1761; 1961;
177 197
178=back 198=back
179 199
180=head1 EXAMPLE 200=head1 EXAMPLE
181 201
182#TODO 202There really should be a complete C/XS example. Bug me about it.
183 203
184=head1 IMPLEMENTATION DETAILS AND LIMITATIONS 204=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
185 205
186This module works by "hijacking" SIGKILL, which is guarenteed to be always 206This module works by "hijacking" SIGKILL, which is guaranteed to be always
187available in perl, but also cannot be caught, so is always available. 207available in perl, but also cannot be caught, so is always available.
188 208
189Basically, this module fakes the receive of a SIGKILL signal and 209Basically, this module fakes the receive of a SIGKILL signal and
190then catches it. This makes normal signal handling slower (probably 210then catches it. This makes normal signal handling slower (probably
191unmeasurably), but has the advantage of not requiring a special runops nor 211unmeasurably), but has the advantage of not requiring a special runops nor
192slowing down normal perl execution a bit. 212slowing down normal perl execution a bit.
193 213
194It 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
195modify (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
196C<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.
197signals). 217signals).
198 218
199=head1 AUTHOR 219=head1 AUTHOR
200 220
201 Marc Lehmann <schmorp@schmorp.de> 221 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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