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

Comparing Async-Interrupt/Interrupt.pm (file contents):
Revision 1.2 by root, Thu Jul 2 15:13:03 2009 UTC vs.
Revision 1.16 by root, Fri Jul 17 21:02:18 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
		90	L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
		91	and C<write> syscall.
		92
		93	=head1 THE Async::Interrupt CLASS
43		94
44	=over 4	95	=over 4
45		96
46	=cut	97	=cut
47		98
48	package Async::Interrupt;	99	package Async::Interrupt;
49		100
50	no warnings;	101	use common::sense;
51		102
52	BEGIN {	103	BEGIN {
		104	# the next line forces initialisation of internal
		105	# signal handling # variables
		106	$SIG{KILL} = sub { };
		107
53	$VERSION = '0.02';	108	our $VERSION = '0.6';
54		109
55	require XSLoader;	110	require XSLoader;
56	XSLoader::load Async::Interrupt::, $VERSION;	111	XSLoader::load ("Async::Interrupt", $VERSION);
57	}	112	}
58		113
59	our $DIED = sub { warn "$@" };	114	our $DIED = sub { warn "$@" };
60		115
61	=item $async = new Async::Interrupt key => value...	116	=item $async = new Async::Interrupt key => value...
…		…
99	C<$value> is the C<value> passed to some earlier call to either C<$signal>	154	C<$value> is the C<value> passed to some earlier call to either C<$signal>
100	or the C<signal_func> function.	155	or the C<signal_func> function.
101		156
102	Note that, because the callback can be invoked at almost any time, you	157	Note that, because the callback can be invoked at almost any time, you
103	have to be careful at saving and restoring global variables that Perl	158	have to be careful at saving and restoring global variables that Perl
104	might use (the excetpion is C<errno>, which is aved and restored by	159	might use (the exception is C<errno>, which is saved and restored by
105	Async::Interrupt). The callback itself runs as part of the perl context,	160	Async::Interrupt). The callback itself runs as part of the perl context,
106	so you can call any perl functions and modify any perl data structures (in	161	so you can call any perl functions and modify any perl data structures (in
107	which case the requireemnts set out for C<cb> apply as well).	162	which case the requirements set out for C<cb> apply as well).
		163
		164	=item var => $scalar_ref
		165
		166	When specified, then the given argument must be a reference to a
		167	scalar. The scalar will be set to C<0> intiially. Signalling the interrupt
		168	object will set it to the passed value, handling the interrupt will reset
		169	it to C<0> again.
		170
		171	Note that the only thing you are legally allowed to do is to is to check
		172	the variable in a boolean or integer context (e.g. comparing it with a
		173	string, or printing it, will I<destroy> it and might cause your program to
		174	crash or worse).
		175
		176	=item signal => $signame_or_value
		177
		178	When this parameter is specified, then the Async::Interrupt will hook the
		179	given signal, that is, it will effectively call C<< ->signal (0) >> each time
		180	the given signal is caught by the process.
		181
		182	Only one async can hook a given signal, and the signal will be restored to
		183	defaults when the Async::Interrupt object gets destroyed.
108		184
109	=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]	185	=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
110		186
111	Specifies two file descriptors (or file handles) that should be signalled	187	Specifies two file descriptors (or file handles) that should be signalled
112	whenever the async interrupt is signalled. This means a single octet will	188	whenever the async interrupt is signalled. This means a single octet will
113	be written to it, and before the callback is being invoked, it will be	189	be written to it, and before the callback is being invoked, it will be
114	read again. Due to races, it is unlikely but possible that multiple octets	190	read again. Due to races, it is unlikely but possible that multiple octets
115	are written. It is required that the file handles are both in nonblocking	191	are written. It is required that the file handles are both in nonblocking
116	mode.	192	mode.
117		193
118	(You can get a portable pipe and set non-blocking mode portably by using
119	e.g. L<AnyEvent::Util> from the L<AnyEvent> distro).
120
121	The object will keep a reference to the file handles.	194	The object will keep a reference to the file handles.
122		195
123	This can be used to ensure that async notifications will interrupt event	196	This can be used to ensure that async notifications will interrupt event
124	frameworks as well.	197	frameworks as well.
125		198
		199	Note that C<Async::Interrupt> will create a suitable signal fd
		200	automatically when your program requests one, so you don't have to specify
		201	this argument when all you want is an extra file descriptor to watch.
		202
		203	If you want to share a single event pipe between multiple Async::Interrupt
		204	objects, you can use the C<Async::Interrupt::EventPipe> class to manage
		205	those.
		206
126	=back	207	=back
127		208
128	=cut	209	=cut
129		210
130	sub new {	211	sub new {
131	my ($class, %arg) = @_;	212	my ($class, %arg) = @_;
132		213
133	bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1]), $class	214	bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class
134	}	215	}
135		216
136	=item ($signal_func, $signal_arg) = $async->signal_func	217	=item ($signal_func, $signal_arg) = $async->signal_func
137		218
138	Returns the address of a function to call asynchronously. The function has	219	Returns the address of a function to call asynchronously. The function has
…		…
146	signal_func (signal_arg, 0);	227	signal_func (signal_arg, 0);
147		228
148	The function is safe to call from within signal and thread contexts, at	229	The function is safe to call from within signal and thread contexts, at
149	any time. The specified C<value> is passed to both C and Perl callback.	230	any time. The specified C<value> is passed to both C and Perl callback.
150		231
151	C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is	232	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
152	portable).	233	(1..127 is portable).
153		234
154	If the function is called while the Async::Interrupt object is already	235	If the function is called while the Async::Interrupt object is already
155	signaled but before the callbacks are being executed, then the stored	236	signaled but before the callbacks are being executed, then the stored
156	C<value> is either the old or the new one. Due to the asynchronous	237	C<value> is either the old or the new one. Due to the asynchronous
157	nature of the code, the C<value> can even be passed to two consecutive	238	nature of the code, the C<value> can even be passed to two consecutive
158	invocations of the callback.	239	invocations of the callback.
159		240
		241	=item $address = $async->c_var
		242
		243	Returns the address (cast to IV) of an C<IV> variable. The variable is set
		244	to C<0> initially and gets set to the passed value whenever the object
		245	gets signalled, and reset to C<0> once the interrupt has been handled.
		246
		247	Note that it is often beneficial to just call C<PERL_ASYNC_CHECK ()> to
		248	handle any interrupts.
		249
		250	Example: call some XS function to store the address, then show C code
		251	waiting for it.
		252
		253	my_xs_func $async->c_var;
		254
		255	static IV *valuep;
		256
		257	void
		258	my_xs_func (void *addr)
		259	CODE:
		260	valuep = (IV *)addr;
		261
		262	// code in a loop, waiting
		263	while (!*valuep)
		264	; // do something
		265
160	=item $async->signal ($value=0)	266	=item $async->signal ($value=1)
161		267
162	This signals the given async object from Perl code. Semi-obviously, this	268	This signals the given async object from Perl code. Semi-obviously, this
163	will instantly trigger the callback invocation.	269	will instantly trigger the callback invocation.
164		270
165	C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is	271	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
166	portable).	272	(1..127 is portable).
167		273
168	=item $async->block	274	=item $async->block
169		275
170	Sometimes you need a "critical section" of code where
171
172	=item $async->unblock	276	=item $async->unblock
173		277
		278	Sometimes you need a "critical section" of code that will not be
		279	interrupted by an Async::Interrupt. This can be implemented by calling C<<
		280	$async->block >> before the critical section, and C<< $async->unblock >>
		281	afterwards.
		282
		283	Note that there must be exactly one call of C<unblock> for every previous
		284	call to C<block> (i.e. calls can nest).
		285
		286	Since ensuring this in the presence of exceptions and threads is
		287	usually more difficult than you imagine, I recommend using C<<
		288	$async->scoped_block >> instead.
		289
		290	=item $async->scope_block
		291
		292	This call C<< $async->block >> and installs a handler that is called when
		293	the current scope is exited (via an exception, by canceling the Coro
		294	thread, by calling last/goto etc.).
		295
		296	This is the recommended (and fastest) way to implement critical sections.
		297
		298	=item $async->pipe_enable
		299
		300	=item $async->pipe_disable
		301
		302	Enable/disable signalling the pipe when the interrupt occurs (default is
		303	enabled). Writing to a pipe is relatively expensive, so it can be disabled
		304	when you know you are not waiting for it (for example, with L<EV> you
		305	could disable the pipe in a check watcher, and enable it in a prepare
		306	watcher).
		307
		308	Note that currently, while C<pipe_disable> is in effect, no attempt to
		309	read from the pipe will be done when handling events. This might change as
		310	soon as I realize why this is a mistake.
		311
		312	=item $fileno = $async->pipe_fileno
		313
		314	Returns the reading side of the signalling pipe. If no signalling pipe is
		315	currently attached to the object, it will dynamically create one.
		316
		317	Note that the only valid oepration on this file descriptor is to wait
		318	until it is readable. The fd might belong currently to a pipe, a tcp
		319	socket, or an eventfd, depending on the platform, and is guaranteed to be
		320	C<select>able.
		321
		322	=item $async->pipe_autodrain ($enable)
		323
		324	Enables (C<1>) or disables (C<0>) automatic draining of the pipe (default:
		325	enabled). When automatic draining is enabled, then Async::Interrupt will
		326	automatically clear the pipe. Otherwise the user is responsible for this
		327	draining.
		328
		329	This is useful when you want to share one pipe among many Async::Interrupt
		330	objects.
		331
		332	=item $async->post_fork
		333
		334	The object will not normally be usable after a fork (as the pipe fd is
		335	shared between processes). Calling this method after a fork in the child
		336	ensures that the object will work as expected again. It only needs to be
		337	called when the async object is used in the child.
		338
		339	This only works when the pipe was created by Async::Interrupt.
		340
		341	Async::Interrupt ensures that the reading file descriptor does not change
		342	it's value.
		343
		344	=back
		345
		346	=head1 THE Async::Interrupt::EventPipe CLASS
		347
		348	Pipes are the predominent utility to make asynchronous signals
		349	synchronous. However, pipes are hard to come by: they don't exist on the
		350	broken windows platform, and on GNU/Linux systems, you might want to use
		351	an C<eventfd> instead.
		352
		353	This class creates selectable event pipes in a portable fashion: on
		354	windows, it will try to create a tcp socket pair, on GNU/Linux, it will
		355	try to create an eventfd and everywhere else it will try to use a normal
		356	pipe.
		357
		358	=over 4
		359
		360	=item $epipe = new Async::Interrupt::EventPipe
		361
		362	This creates and returns an eventpipe object. This object is simply a
		363	blessed array reference:
		364
		365	=item ($r_fd, $w_fd) = $epipe->filenos
		366
		367	Returns the read-side file descriptor and the write-side file descriptor.
		368
		369	Example: pass an eventpipe object as pipe to the Async::Interrupt
		370	constructor, and create an AnyEvent watcher for the read side.
		371
		372	my $epipe = new Async::Interrupt::EventPipe;
		373	my $asy = new Async::Interrupt pipe => [$epipe->filenos];
		374	my $iow = AnyEvent->io (fh => $epipe->fileno, poll => 'r', cb => sub { });
		375
		376	=item $r_fd = $epipe->fileno
		377
		378	Return only the reading/listening side.
		379
		380	=item $epipe->signal
		381
		382	Write something to the pipe, in a portable fashion.
		383
		384	=item $epipe->drain
		385
		386	Drain (empty) the pipe.
		387
		388	=item $epipe->renew
		389
		390	Recreates the pipe (useful after a fork). The reading side will not change
		391	it's file descriptor number, but the writing side might.
		392
		393	=back
		394
174	=cut	395	=cut
175		396
176	1;	397	1;
177		398
178	=back
179
180	=head1 EXAMPLE	399	=head1 EXAMPLE
181		400
182	#TODO	401	There really should be a complete C/XS example. Bug me about it. Better
		402	yet, create one.
183		403
184	=head1 IMPLEMENTATION DETAILS AND LIMITATIONS	404	=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
185		405
186	This module works by "hijacking" SIGKILL, which is guarenteed to be always	406	This module works by "hijacking" SIGKILL, which is guaranteed to always
187	available in perl, but also cannot be caught, so is always available.	407	exist, but also cannot be caught, so is always available.
188		408
189	Basically, this module fakes the receive of a SIGKILL signal and	409	Basically, this module fakes the occurance of a SIGKILL signal and
190	then catches it. This makes normal signal handling slower (probably	410	then intercepts the interpreter handling it. This makes normal signal
191	unmeasurably), but has the advantage of not requiring a special runops nor	411	handling slower (probably unmeasurably, though), but has the advantage
192	slowing down normal perl execution a bit.	412	of not requiring a special runops function, nor slowing down normal perl
		413	execution a bit.
193		414
194	It assumes that C<sig_atomic_t> and C<int> are both exception-safe to	415	It assumes that C<sig_atomic_t>, C<int> and C<IV> are all async-safe to
195	modify (C<sig_atomic_> is used by this module, and perl itself uses	416	modify.
196	C<int>, so we can assume that this is quite portbale, at least w.r.t.
197	signals).
198		417
199	=head1 AUTHOR	418	=head1 AUTHOR
200		419
201	Marc Lehmann <schmorp@schmorp.de>	420	Marc Lehmann <schmorp@schmorp.de>
202	http://home.schmorp.de/	421	http://home.schmorp.de/

Diff Legend

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

Comparing Async-Interrupt/Interrupt.pm (file contents): Revision 1.2 by root, Thu Jul 2 15:13:03 2009 UTC vs. Revision 1.16 by root, Fri Jul 17 21:02:18 2009 UTC

Diff Legend

Comparing Async-Interrupt/Interrupt.pm (file contents):
Revision 1.2 by root, Thu Jul 2 15:13:03 2009 UTC vs.
Revision 1.16 by root, Fri Jul 17 21:02:18 2009 UTC