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.1 by root, Thu Jul 2 13:41:44 2009 UTC vs.
Revision 1.5 by root, Fri Jul 3 21:11:22 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
… …
21 21
22This module implements asynchronous notifications that enable you to 22This module implements asynchronous notifications that enable you to
23signal running perl code form another thread, asynchronously, without 23signal running perl code form another thread, asynchronously, without
24issuing syscalls. 24issuing syscalls.
25 25
26It works by creating an C<Async::Interrupt> object for each such use. This
27object stores a perl and/or a C-level callback that is invoked when the
28C<Async::Interrupt> object gets signalled. It is executed at the next time
29the perl interpreter is running (i.e. it will interrupt a computation, but
30not an XS function or a syscall).
31
32You can signal the C<Async::Interrupt> object either by calling it's C<<
33->signal >> method, or, more commonly, by calling a C function.
34
35The C<< ->signal_func >> returns the address of the C function that is to
36be called (plus an argument to be used during the call). The signalling
37function also takes an integer argument in the range SIG_ATOMIC_MIN to
38SIG_ATOMIC_MAX (guaranteed to allow at least 0..127).
39
40Since this kind of interruption is fast, but can only interrupt 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 (e.g.
43via L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a
44C<read> and C<write> syscall.
45
26=over 4 46=over 4
27 47
28=cut 48=cut
29 49
30package Async::Interrupt; 50package Async::Interrupt;
31 51
52no warnings;
53
32BEGIN { 54BEGIN {
33 $VERSION = '0.02'; 55 $VERSION = '0.03';
34 56
35 require XSLoader; 57 require XSLoader;
36 XSLoader::load Async::Interrupt::, $VERSION; 58 XSLoader::load Async::Interrupt::, $VERSION;
37} 59}
38 60
61our $DIED = sub { warn "$@" };
62
39=item $async = new Async::Interrupt key => value... 63=item $async = new Async::Interrupt key => value...
40 64
41Creates a new Async::Interrupt object. You may only use async 65Creates a new Async::Interrupt object. You may only use async
42notifications on this object while it exists, so you need to keep a 66notifications on this object while it exists, so you need to keep a
43reference to it at all times while it is used. 67reference to it at all times while it is used.
… …
51 75
52Registers a perl callback to be invoked whenever the async interrupt is 76Registers a perl callback to be invoked whenever the async interrupt is
53signalled. 77signalled.
54 78
55Note that, since this callback can be invoked at basically any time, it 79Note that, since this callback can be invoked at basically any time, it
56must not modify any well-known global variables such as C<$/>, C<$@> or 80must not modify any well-known global variables such as C<$/> without
57C<$!>, without restoring them again before returning. 81restoring them again before returning.
58 82
83The exceptions are C<$!> and C<$@>, which are saved and restored by
84Async::Interrupt.
85
86If the callback should throw an exception, then it will be caught,
87and C<$Async::Interrupt::DIED> will be called with C<$@> containing
88the exception. The default will simply C<warn> about the message and
89continue.
90
59=item c_cb => [$c_func, $c_data] 91=item c_cb => [$c_func, $c_arg]
60 92
61Registers a C callback the be invoked whenever the async interrupt is 93Registers a C callback the be invoked whenever the async interrupt is
62signalled. 94signalled.
63 95
64The C callback must have the following prototype: 96The C callback must have the following prototype:
65 97
66 void c_func (pTHX_ void *c_data, int value); 98 void c_func (pTHX_ void *c_arg, int value);
67 99
68Both C<$c_func> and C<$c_data> must be specified as integers/IVs. 100Both C<$c_func> and C<$c_arg> must be specified as integers/IVs, and
101C<$value> is the C<value> passed to some earlier call to either C<$signal>
102or the C<signal_func> function.
69 103
70Note 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
71have to be careful at saving and restoring global variables that Perl 105have to be careful at saving and restoring global variables that Perl
72might use, most notably C<errno>. The callback itself runs as part of the 106might use (the exception is C<errno>, which is saved and restored by
73perl context, so you can call any perl functions and modify any perl data 107Async::Interrupt). The callback itself runs as part of the perl context,
74structures. 108so you can call any perl functions and modify any perl data structures (in
109which case the requirements set out for C<cb> apply as well).
75 110
76=item fh => $fileno_or_fh 111=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
77 112
78Specifies a file descriptor (or file handle) that should be signalled 113Specifies two file descriptors (or file handles) that should be signalled
79whenever the async interrupt is signalled. This means a single octet will 114whenever the async interrupt is signalled. This means a single octet will
80be written to it, and before the callback is being invoked, it will be 115be written to it, and before the callback is being invoked, it will be
81read 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
82are written, therefore, it is recommended that the file handle is in 117are written. It is required that the file handles are both in nonblocking
83nonblocking mode. 118mode.
84 119
85(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
86e.g. L<AnyEvent::Util> from the L<AnyEvent> distro). 121e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution).
87 122
88The object will keep a reference to the file handle. 123The object will keep a reference to the file handles.
89 124
90This can be used to ensure that async notifications will interrupt event 125This can be used to ensure that async notifications will interrupt event
91frameworks as well. 126frameworks as well.
92 127
93=back 128=back
… …
95=cut 130=cut
96 131
97sub new { 132sub new {
98 my ($class, %arg) = @_; 133 my ($class, %arg) = @_;
99 134
100 my $self = _alloc $arg{cb}, @{$arg{c_cb}}[0,1], $arg{fh}; 135 bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1]), $class
101 bless \$self, $class
102} 136}
103 137
104=item ($signal_func, $signal_arg) = $async->signal_cb 138=item ($signal_func, $signal_arg) = $async->signal_func
105 139
106Returns the address of a function to call asynchronously. The function has 140Returns the address of a function to call asynchronously. The function has
107the following prototype and needs to be passed the specified C<$c_arg>, 141the following prototype and needs to be passed the specified C<$c_arg>,
108which is a C<void *> cast to C<IV>: 142which is a C<void *> cast to C<IV>:
109 143
… …
111 145
112An example call would look like: 146An example call would look like:
113 147
114 signal_func (signal_arg, 0); 148 signal_func (signal_arg, 0);
115 149
116The function is safe toc all from within signal and thread contexts, at 150The function is safe to call from within signal and thread contexts, at
117any time. The specified C<value> is passed to both C and Perl callback. 151any time. The specified C<value> is passed to both C and Perl callback.
152
153C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is
154portable).
118 155
119If the function is called while the Async::Interrupt object is already 156If the function is called while the Async::Interrupt object is already
120signaled but before the callbacks are being executed, then the stored 157signaled but before the callbacks are being executed, then the stored
121C<value> is being overwritten. Due to the asynchronous nature of the code, 158C<value> is either the old or the new one. Due to the asynchronous
122the C<value> can even be passed to two consecutive invocations of the 159nature of the code, the C<value> can even be passed to two consecutive
123callback. 160invocations of the callback.
124 161
125=item $async->signal ($value=0) 162=item $async->signal ($value=0)
126 163
127This signals the given async object from Perl code. Semi-obviously, this 164This signals the given async object from Perl code. Semi-obviously, this
128will instantly trigger the callback invocation. 165will instantly trigger the callback invocation.
129 166
167C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is
168portable).
169
170=item $async->block
171
172=item $async->unblock
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
130=cut 194=cut
131 195
1321; 1961;
133 197
134=back 198=back
199
200=head1 EXAMPLE
201
202There really should be a complete C/XS example. Bug me about it.
203
204=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
205
206This module works by "hijacking" SIGKILL, which is guaranteed to be always
207available in perl, but also cannot be caught, so is always available.
208
209Basically, this module fakes the receive of a SIGKILL signal and
210then catches it. This makes normal signal handling slower (probably
211unmeasurably), but has the advantage of not requiring a special runops nor
212slowing down normal perl execution a bit.
213
214It assumes that C<sig_atomic_t> and C<int> are both exception-safe to
215modify (C<sig_atomic_> is used by this module, and perl itself uses
216C<int>, so we can assume that this is quite portable, at least w.r.t.
217signals).
135 218
136=head1 AUTHOR 219=head1 AUTHOR
137 220
138 Marc Lehmann <schmorp@schmorp.de> 221 Marc Lehmann <schmorp@schmorp.de>
139 http://home.schmorp.de/ 222 http://home.schmorp.de/

Diff Legend

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