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.3 by root, Thu Jul 2 16:12:40 2009 UTC

… …
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 while
43#TODO#
44
26=over 4 45=over 4
27 46
28=cut 47=cut
29 48
30package Async::Interrupt; 49package Async::Interrupt;
50
51no warnings;
31 52
32BEGIN { 53BEGIN {
33 $VERSION = '0.02'; 54 $VERSION = '0.02';
34 55
35 require XSLoader; 56 require XSLoader;
36 XSLoader::load Async::Interrupt::, $VERSION; 57 XSLoader::load Async::Interrupt::, $VERSION;
37} 58}
38 59
60our $DIED = sub { warn "$@" };
61
39=item $async = new Async::Interrupt key => value... 62=item $async = new Async::Interrupt key => value...
40 63
41Creates a new Async::Interrupt object. You may only use async 64Creates a new Async::Interrupt object. You may only use async
42notifications on this object while it exists, so you need to keep a 65notifications on this object while it exists, so you need to keep a
43reference to it at all times while it is used. 66reference to it at all times while it is used.
… …
51 74
52Registers a perl callback to be invoked whenever the async interrupt is 75Registers a perl callback to be invoked whenever the async interrupt is
53signalled. 76signalled.
54 77
55Note that, since this callback can be invoked at basically any time, it 78Note 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 79must not modify any well-known global variables such as C<$/> without
57C<$!>, without restoring them again before returning. 80restoring them again before returning.
58 81
82The exceptions are C<$!> and C<$@>, which are saved and restored by
83Async::Interrupt.
84
85If the callback should throw an exception, then it will be caught,
86and C<$Async::Interrupt::DIED> will be called with C<$@> containing
87the exception. The default will simply C<warn> about the message and
88continue.
89
59=item c_cb => [$c_func, $c_data] 90=item c_cb => [$c_func, $c_arg]
60 91
61Registers a C callback the be invoked whenever the async interrupt is 92Registers a C callback the be invoked whenever the async interrupt is
62signalled. 93signalled.
63 94
64The C callback must have the following prototype: 95The C callback must have the following prototype:
65 96
66 void c_func (pTHX_ void *c_data, int value); 97 void c_func (pTHX_ void *c_arg, int value);
67 98
68Both C<$c_func> and C<$c_data> must be specified as integers/IVs. 99Both C<$c_func> and C<$c_arg> must be specified as integers/IVs, and
100C<$value> is the C<value> passed to some earlier call to either C<$signal>
101or the C<signal_func> function.
69 102
70Note that, because the callback can be invoked at almost any time, you 103Note that, because the callback can be invoked at almost any time, you
71have to be careful at saving and restoring global variables that Perl 104have 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 105might use (the excetpion is C<errno>, which is aved and restored by
73perl context, so you can call any perl functions and modify any perl data 106Async::Interrupt). The callback itself runs as part of the perl context,
74structures. 107so 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).
75 109
76=item fh => $fileno_or_fh 110=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
77 111
78Specifies a file descriptor (or file handle) that should be signalled 112Specifies two file descriptors (or file handles) that should be signalled
79whenever the async interrupt is signalled. This means a single octet will 113whenever 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 114be 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 115read again. Due to races, it is unlikely but possible that multiple octets
82are written, therefore, it is recommended that the file handle is in 116are written. It is required that the file handles are both in nonblocking
83nonblocking mode. 117mode.
84 118
85(You can get a portable pipe and set non-blocking mode portably by using 119(You can get a portable pipe and set non-blocking mode portably by using
86e.g. L<AnyEvent::Util> from the L<AnyEvent> distro). 120e.g. L<AnyEvent::Util> from the L<AnyEvent> distro).
87 121
88The object will keep a reference to the file handle. 122The object will keep a reference to the file handles.
89 123
90This can be used to ensure that async notifications will interrupt event 124This can be used to ensure that async notifications will interrupt event
91frameworks as well. 125frameworks as well.
92 126
93=back 127=back
… …
95=cut 129=cut
96 130
97sub new { 131sub new {
98 my ($class, %arg) = @_; 132 my ($class, %arg) = @_;
99 133
100 my $self = _alloc $arg{cb}, @{$arg{c_cb}}[0,1], $arg{fh}; 134 bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1]), $class
101 bless \$self, $class
102} 135}
103 136
104=item ($signal_func, $signal_arg) = $async->signal_cb 137=item ($signal_func, $signal_arg) = $async->signal_func
105 138
106Returns the address of a function to call asynchronously. The function has 139Returns the address of a function to call asynchronously. The function has
107the following prototype and needs to be passed the specified C<$c_arg>, 140the following prototype and needs to be passed the specified C<$c_arg>,
108which is a C<void *> cast to C<IV>: 141which is a C<void *> cast to C<IV>:
109 142
… …
111 144
112An example call would look like: 145An example call would look like:
113 146
114 signal_func (signal_arg, 0); 147 signal_func (signal_arg, 0);
115 148
116The function is safe toc all from within signal and thread contexts, at 149The 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. 150any time. The specified C<value> is passed to both C and Perl callback.
151
152C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is
153portable).
118 154
119If the function is called while the Async::Interrupt object is already 155If the function is called while the Async::Interrupt object is already
120signaled but before the callbacks are being executed, then the stored 156signaled but before the callbacks are being executed, then the stored
121C<value> is being overwritten. Due to the asynchronous nature of the code, 157C<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 158nature of the code, the C<value> can even be passed to two consecutive
123callback. 159invocations of the callback.
124 160
125=item $async->signal ($value=0) 161=item $async->signal ($value=0)
126 162
127This signals the given async object from Perl code. Semi-obviously, this 163This signals the given async object from Perl code. Semi-obviously, this
128will instantly trigger the callback invocation. 164will instantly trigger the callback invocation.
129 165
166C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is
167portable).
168
169=item $async->block
170
171=item $async->unblock
172
173Sometimes you need a "critical section" of code that will not be
174interrupted by an Async::Interrupt. This can be implemented by calling C<<
175$async->block >> before the critical section, and C<< $async->unblock >>
176afterwards.
177
178Note that there must be exactly one call of C<unblock> for ever<y previous
179call to C<block> (i.e. calls can nest).
180
181Since ensuring this in the presense of exceptions and threads is
182usually more difficult than you imagine, I recommend using C<<
183$async->scoped_block >> instead.
184
185=item $async->scope_block
186
187This call C<< $async->block >> and installs a handler that is called when
188the current scope is exited (via an exception, by canceling the Coro
189thread, by calling last/goto etc.).
190
191This is the recommended (and fastest) way to implement critical sections.
192
130=cut 193=cut
131 194
1321; 1951;
133 196
134=back 197=back
198
199=head1 EXAMPLE
200
201#TODO
202
203=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
204
205This module works by "hijacking" SIGKILL, which is guarenteed to be always
206available in perl, but also cannot be caught, so is always available.
207
208Basically, this module fakes the receive of a SIGKILL signal and
209then catches it. This makes normal signal handling slower (probably
210unmeasurably), but has the advantage of not requiring a special runops nor
211slowing down normal perl execution a bit.
212
213It 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
215C<int>, so we can assume that this is quite portbale, at least w.r.t.
216signals).
135 217
136=head1 AUTHOR 218=head1 AUTHOR
137 219
138 Marc Lehmann <schmorp@schmorp.de> 220 Marc Lehmann <schmorp@schmorp.de>
139 http://home.schmorp.de/ 221 http://home.schmorp.de/

Diff Legend

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