[ViewVC] Diff of: cvs/cvsroot/Async-Interrupt/Interrupt.pm

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.3 by root, Thu Jul 2 16:12:40 2009 UTC vs.
Revision 1.13 by root, Fri Jul 17 01:51:32 2009 UTC

…		…
7	use Async::Interrupt;	7	use Async::Interrupt;
8		8
9	=head1 DESCRIPTION	9	=head1 DESCRIPTION
10		10
11	This module implements a single feature only of interest to advanced perl	11	This module implements a single feature only of interest to advanced perl
12	modules, namely asynchronous interruptions (think "unix signals", which	12	modules, namely asynchronous interruptions (think "UNIX signals", which
13	are very similar).	13	are very similar).
14		14
15	Sometimes, modules wish to run code asynchronously (in another thread),	15	Sometimes, modules wish to run code asynchronously (in another thread,
16	and then signal the perl interpreter on certain events. One common way is	16	or from a signal handler), and then signal the perl interpreter on
17	to write some data to a pipe and use an event handling toolkit to watch	17	certain events. One common way is to write some data to a pipe and use an
18	for I/O events. Another way is to send a signal. Those methods are slow,	18	event handling toolkit to watch for I/O events. Another way is to send
19	and in the case of a pipe, also not asynchronous - it won't interrupt a	19	a signal. Those methods are slow, and in the case of a pipe, also not
20	running perl interpreter.	20	asynchronous - it won't interrupt a running perl interpreter.
21		21
22	This module implements asynchronous notifications that enable you to	22	This module implements asynchronous notifications that enable you to
23	signal running perl code form another thread, asynchronously, without	23	signal running perl code from another thread, asynchronously, and
24	issuing syscalls.	24	sometimes even without using a single syscall.
25		25
26	It works by creating an C<Async::Interrupt> object for each such use. This	26	=head2 USAGE SCENARIOS
27	object stores a perl and/or a C-level callback that is invoked when the	27
28	C<Async::Interrupt> object gets signalled. It is executed at the next time	28	=over 4
29	the perl interpreter is running (i.e. it will interrupt a computation, but	29
30	not an XS function or a syscall).	30	=item Race-free signal handling
		31
		32	There seems to be no way to do race-free signal handling in perl: to
		33	catch a signal, you have to execute Perl code, and between entering the
		34	interpreter C<select> function (or other blocking functions) and executing
		35	the select syscall is a small but relevant timespan during which signals
		36	will be queued, but perl signal handlers will not be executed and the
		37	blocking syscall will not be interrupted.
		38
		39	You can use this module to bind a signal to a callback while at the same
		40	time activating an event pipe that you can C<select> on, fixing the race
		41	completely.
		42
		43	This can be used to implement the signal hadling in event loops,
		44	e.g. L<AnyEvent>, L<POE>, L<IO::Async::Loop> and so on.
		45
		46	=item Background threads want speedy reporting
		47
		48	Assume you want very exact timing, and you can spare an extra cpu core
		49	for that. Then you can run an extra thread that signals your perl
		50	interpreter. This means you can get a very exact timing source while your
		51	perl code is number crunching, without even using a syscall to communicate
		52	between your threads.
		53
		54	For example the deliantra game server uses a variant of this technique
		55	to interrupt background processes regularly to send map updates to game
		56	clients.
		57
		58	L<IO::AIO> and L<BDB> could also use this to speed up result reporting.
		59
		60	=item Speedy event loop invocation
		61
		62	One could use this module e.g. in L<Coro> to interrupt a running coro-thread
		63	and cause it to enter the event loop.
		64
		65	Or one could bind to C<SIGIO> and tell some important sockets to send this
		66	signal, causing the event loop to be entered to reduce network latency.
		67
		68	=back
		69
		70	=head2 HOW TO USE
		71
		72	You can use this module by creating an C<Async::Interrupt> object for each
		73	such event source. This object stores a perl and/or a C-level callback
		74	that is invoked when the C<Async::Interrupt> object gets signalled. It is
		75	executed at the next time the perl interpreter is running (i.e. it will
		76	interrupt a computation, but not an XS function or a syscall).
31		77
32	You can signal the C<Async::Interrupt> object either by calling it's C<<	78	You can signal the C<Async::Interrupt> object either by calling it's C<<
33	->signal >> method, or, more commonly, by calling a C function.	79	->signal >> method, or, more commonly, by calling a C function. There is
		80	also the built-in (POSIX) signal source.
34		81
35	The C<< ->signal_func >> returns the address of the C function that is to	82	The C<< ->signal_func >> returns the address of the C function that is to
36	be called (plus an argument to be used during the call). The signalling	83	be called (plus an argument to be used during the call). The signalling
37	function also takes an integer argument in the range SIG_ATOMIC_MIN to	84	function also takes an integer argument in the range SIG_ATOMIC_MIN to
38	SIG_ATOMIC_MAX (guaranteed to allow at least 0..127).	85	SIG_ATOMIC_MAX (guaranteed to allow at least 0..127).
39		86
40	Since this kind of interruption is fast, but can only interrupt a	87	Since this kind of interruption is fast, but can only interrupt a
41	I<running> interpreter, there is optional support for also signalling a	88	I<running> interpreter, there is optional support for signalling a pipe
42	pipe - that means you can also wait for the pipe to become readable while	89	- that means you can also wait for the pipe to become readable (e.g. via
43	#TODO#	90	L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
		91	and C<write> syscall.
44		92
45	=over 4	93	=over 4
46		94
47	=cut	95	=cut
48		96
49	package Async::Interrupt;	97	package Async::Interrupt;
50		98
51	no warnings;	99	use common::sense;
52		100
53	BEGIN {	101	BEGIN {
		102	# the next line forces initialisation of internal
		103	# signal handling # variables
		104	$SIG{KILL} = sub { };
		105
54	$VERSION = '0.02';	106	our $VERSION = '0.042';
55		107
56	require XSLoader;	108	require XSLoader;
57	XSLoader::load Async::Interrupt::, $VERSION;	109	XSLoader::load ("Async::Interrupt", $VERSION);
58	}	110	}
59		111
60	our $DIED = sub { warn "$@" };	112	our $DIED = sub { warn "$@" };
61		113
62	=item $async = new Async::Interrupt key => value...	114	=item $async = new Async::Interrupt key => value...
…		…
100	C<$value> is the C<value> passed to some earlier call to either C<$signal>	152	C<$value> is the C<value> passed to some earlier call to either C<$signal>
101	or the C<signal_func> function.	153	or the C<signal_func> function.
102		154
103	Note that, because the callback can be invoked at almost any time, you	155	Note that, because the callback can be invoked at almost any time, you
104	have to be careful at saving and restoring global variables that Perl	156	have to be careful at saving and restoring global variables that Perl
105	might use (the excetpion is C<errno>, which is aved and restored by	157	might use (the exception is C<errno>, which is saved and restored by
106	Async::Interrupt). The callback itself runs as part of the perl context,	158	Async::Interrupt). The callback itself runs as part of the perl context,
107	so you can call any perl functions and modify any perl data structures (in	159	so you can call any perl functions and modify any perl data structures (in
108	which case the requireemnts set out for C<cb> apply as well).	160	which case the requirements set out for C<cb> apply as well).
		161
		162	=item var => $scalar_ref
		163
		164	When specified, then the given argument must be a reference to a
		165	scalar. The scalar will be set to C<0> intiially. Signalling the interrupt
		166	object will set it to the passed value, handling the interrupt will reset
		167	it to C<0> again.
		168
		169	Note that the only thing you are legally allowed to do is to is to check
		170	the variable in a boolean or integer context (e.g. comparing it with a
		171	string, or printing it, will I<destroy> it and might cause your program to
		172	crash or worse).
		173
		174	=item signal => $signame_or_value
		175
		176	When this parameter is specified, then the Async::Interrupt will hook the
		177	given signal, that is, it will effectively call C<< ->signal (0) >> each time
		178	the given signal is caught by the process.
		179
		180	Only one async can hook a given signal, and the signal will be restored to
		181	defaults when the Async::Interrupt object gets destroyed.
109		182
110	=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]	183	=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
111		184
112	Specifies two file descriptors (or file handles) that should be signalled	185	Specifies two file descriptors (or file handles) that should be signalled
113	whenever the async interrupt is signalled. This means a single octet will	186	whenever the async interrupt is signalled. This means a single octet will
114	be written to it, and before the callback is being invoked, it will be	187	be written to it, and before the callback is being invoked, it will be
115	read again. Due to races, it is unlikely but possible that multiple octets	188	read again. Due to races, it is unlikely but possible that multiple octets
116	are written. It is required that the file handles are both in nonblocking	189	are written. It is required that the file handles are both in nonblocking
117	mode.	190	mode.
118		191
119	(You can get a portable pipe and set non-blocking mode portably by using
120	e.g. L<AnyEvent::Util> from the L<AnyEvent> distro).
121
122	The object will keep a reference to the file handles.	192	The object will keep a reference to the file handles.
123		193
124	This can be used to ensure that async notifications will interrupt event	194	This can be used to ensure that async notifications will interrupt event
125	frameworks as well.	195	frameworks as well.
126		196
		197	Note that C<Async::Interrupt> will create a suitable signal fd
		198	automatically when your program requests one, so you don't have to specify
		199	this agrument when all you want is an extra file descriptor to watch.
		200
127	=back	201	=back
128		202
129	=cut	203	=cut
130		204
131	sub new {	205	sub new {
132	my ($class, %arg) = @_;	206	my ($class, %arg) = @_;
133		207
134	bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1]), $class	208	bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class
135	}	209	}
136		210
137	=item ($signal_func, $signal_arg) = $async->signal_func	211	=item ($signal_func, $signal_arg) = $async->signal_func
138		212
139	Returns the address of a function to call asynchronously. The function has	213	Returns the address of a function to call asynchronously. The function has
…		…
147	signal_func (signal_arg, 0);	221	signal_func (signal_arg, 0);
148		222
149	The function is safe to call from within signal and thread contexts, at	223	The function is safe to call from within signal and thread contexts, at
150	any time. The specified C<value> is passed to both C and Perl callback.	224	any time. The specified C<value> is passed to both C and Perl callback.
151		225
152	C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is	226	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
153	portable).	227	(1..127 is portable).
154		228
155	If the function is called while the Async::Interrupt object is already	229	If the function is called while the Async::Interrupt object is already
156	signaled but before the callbacks are being executed, then the stored	230	signaled but before the callbacks are being executed, then the stored
157	C<value> is either the old or the new one. Due to the asynchronous	231	C<value> is either the old or the new one. Due to the asynchronous
158	nature of the code, the C<value> can even be passed to two consecutive	232	nature of the code, the C<value> can even be passed to two consecutive
159	invocations of the callback.	233	invocations of the callback.
160		234
		235	=item $address = $async->c_var
		236
		237	Returns the address (cast to IV) of an C<IV> variable. The variable is set
		238	to C<0> initially and gets set to the passed value whenever the object
		239	gets signalled, and reset to C<0> once the interrupt has been handled.
		240
		241	Note that it is often beneficial to just call C<PERL_ASYNC_CHECK ()> to
		242	handle any interrupts.
		243
		244	Example: call some XS function to store the address, then show C code
		245	waiting for it.
		246
		247	my_xs_func $async->c_var;
		248
		249	static IV *valuep;
		250
		251	void
		252	my_xs_func (void *addr)
		253	CODE:
		254	valuep = (IV *)addr;
		255
		256	// code in a loop, waiting
		257	while (!*valuep)
		258	; // do soemthing
		259
161	=item $async->signal ($value=0)	260	=item $async->signal ($value=1)
162		261
163	This signals the given async object from Perl code. Semi-obviously, this	262	This signals the given async object from Perl code. Semi-obviously, this
164	will instantly trigger the callback invocation.	263	will instantly trigger the callback invocation.
165		264
166	C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is	265	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
167	portable).	266	(1..127 is portable).
168		267
169	=item $async->block	268	=item $async->block
170		269
171	=item $async->unblock	270	=item $async->unblock
172		271
173	Sometimes you need a "critical section" of code that will not be	272	Sometimes you need a "critical section" of code that will not be
174	interrupted by an Async::Interrupt. This can be implemented by calling C<<	273	interrupted by an Async::Interrupt. This can be implemented by calling C<<
175	$async->block >> before the critical section, and C<< $async->unblock >>	274	$async->block >> before the critical section, and C<< $async->unblock >>
176	afterwards.	275	afterwards.
177		276
178	Note that there must be exactly one call of C<unblock> for ever<y previous	277	Note that there must be exactly one call of C<unblock> for every previous
179	call to C<block> (i.e. calls can nest).	278	call to C<block> (i.e. calls can nest).
180		279
181	Since ensuring this in the presense of exceptions and threads is	280	Since ensuring this in the presence of exceptions and threads is
182	usually more difficult than you imagine, I recommend using C<<	281	usually more difficult than you imagine, I recommend using C<<
183	$async->scoped_block >> instead.	282	$async->scoped_block >> instead.
184		283
185	=item $async->scope_block	284	=item $async->scope_block
186		285
…		…
188	the current scope is exited (via an exception, by canceling the Coro	287	the current scope is exited (via an exception, by canceling the Coro
189	thread, by calling last/goto etc.).	288	thread, by calling last/goto etc.).
190		289
191	This is the recommended (and fastest) way to implement critical sections.	290	This is the recommended (and fastest) way to implement critical sections.
192		291
		292	=item $async->pipe_enable
		293
		294	=item $async->pipe_disable
		295
		296	Enable/disable signalling the pipe when the interrupt occurs (default is
		297	enabled). Writing to a pipe is relatively expensive, so it can be disabled
		298	when you know you are not waiting for it (for example, with L<EV> you
		299	could disable the pipe in a check watcher, and enable it in a prepare
		300	watcher).
		301
		302	Note that currently, while C<pipe_disable> is in effect, no attempt to
		303	read from the pipe will be done when handling events. This might change as
		304	soon as I realize why this is a mistake.
		305
		306	=item $fileno = $async->pipe_fileno
		307
		308	Returns the reading side of the signalling pipe. If no signalling pipe is
		309	currently attached to the object, it will dynamically create one.
		310
		311	Note that the only valid oepration on this file descriptor is to wait
		312	until it is readable. The fd might belong currently to a pipe, a tcp
		313	socket, or an eventfd, depending on the platform, and is guaranteed to be
		314	C<select>able.
		315
		316	=item $async->post_fork
		317
		318	The object will not normally be usable after a fork (as the pipe fd is
		319	shared between processes). Calling this method after a fork in the child
		320	ensures that the object will work as expected again. It only needs to be
		321	called when the async object is used in the child.
		322
		323	This only works when the pipe was created by Async::Interrupt.
		324
		325	Async::Interrupt ensures that the reading file descriptor does not change
		326	it's value.
		327
193	=cut	328	=cut
194		329
195	1;	330	1;
196		331
197	=back	332	=back
198		333
199	=head1 EXAMPLE	334	=head1 EXAMPLE
200		335
201	#TODO	336	There really should be a complete C/XS example. Bug me about it. Better
		337	yet, create one.
202		338
203	=head1 IMPLEMENTATION DETAILS AND LIMITATIONS	339	=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
204		340
205	This module works by "hijacking" SIGKILL, which is guarenteed to be always	341	This module works by "hijacking" SIGKILL, which is guaranteed to always
206	available in perl, but also cannot be caught, so is always available.	342	exist, but also cannot be caught, so is always available.
207		343
208	Basically, this module fakes the receive of a SIGKILL signal and	344	Basically, this module fakes the occurance of a SIGKILL signal and
209	then catches it. This makes normal signal handling slower (probably	345	then intercepts the interpreter handling it. This makes normal signal
210	unmeasurably), but has the advantage of not requiring a special runops nor	346	handling slower (probably unmeasurably, though), but has the advantage
211	slowing down normal perl execution a bit.	347	of not requiring a special runops function, nor slowing down normal perl
		348	execution a bit.
212		349
213	It assumes that C<sig_atomic_t> and C<int> are both exception-safe to	350	It assumes that C<sig_atomic_t>, C<int> and C<IV> are all async-safe to
214	modify (C<sig_atomic_> is used by this module, and perl itself uses	351	modify.
215	C<int>, so we can assume that this is quite portbale, at least w.r.t.
216	signals).
217		352
218	=head1 AUTHOR	353	=head1 AUTHOR
219		354
220	Marc Lehmann <schmorp@schmorp.de>	355	Marc Lehmann <schmorp@schmorp.de>
221	http://home.schmorp.de/	356	http://home.schmorp.de/

Diff Legend

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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents): Revision 1.3 by root, Thu Jul 2 16:12:40 2009 UTC vs. Revision 1.13 by root, Fri Jul 17 01:51:32 2009 UTC

Diff Legend

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.3 by root, Thu Jul 2 16:12:40 2009 UTC vs.
Revision 1.13 by root, Fri Jul 17 01:51:32 2009 UTC