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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.2 by root, Thu Jul 2 15:13:03 2009 UTC vs.
Revision 1.18 by root, Tue Jul 28 12:50:16 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	Or L<EV::Loop::Async> uses an interrupt object to wake up perl when new
		59	events have arrived.
		60
		61	L<IO::AIO> and L<BDB> could also use this to speed up result reporting.
		62
		63	=item Speedy event loop invocation
		64
		65	One could use this module e.g. in L<Coro> to interrupt a running coro-thread
		66	and cause it to enter the event loop.
		67
		68	Or one could bind to C<SIGIO> and tell some important sockets to send this
		69	signal, causing the event loop to be entered to reduce network latency.
		70
		71	=back
		72
		73	=head2 HOW TO USE
		74
		75	You can use this module by creating an C<Async::Interrupt> object for each
		76	such event source. This object stores a perl and/or a C-level callback
		77	that is invoked when the C<Async::Interrupt> object gets signalled. It is
		78	executed at the next time the perl interpreter is running (i.e. it will
		79	interrupt a computation, but not an XS function or a syscall).
31		80
32	You can signal the C<Async::Interrupt> object either by calling it's C<<	81	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.	82	->signal >> method, or, more commonly, by calling a C function. There is
		83	also the built-in (POSIX) signal source.
34		84
35	The C<< ->signal_func >> returns the address of the C function that is to	85	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	86	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	87	function also takes an integer argument in the range SIG_ATOMIC_MIN to
38	SIG_ATOMIC_MAX (guaranteed to allow at least 0..127).	88	SIG_ATOMIC_MAX (guaranteed to allow at least 0..127).
39		89
40	Since this kind of interruption is fast, but can only interrupt a	90	Since this kind of interruption is fast, but can only interrupt a
41	I<running> interpreter, there is optional support for also signalling a	91	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	92	- that means you can also wait for the pipe to become readable (e.g. via
		93	L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
		94	and C<write> syscall.
		95
		96	=head1 USAGE EXAMPLES
		97
		98	=head2 Async::Interrupt to implement race-free signal handling
		99
		100	This example uses a single event pipe for all signals, and one
		101	Async::Interrupt per signal.
		102
		103	First, create the event pipe and hook it into the event loop (this code is
		104	actually what L<AnyEvent> uses itself):
		105
		106	$SIGPIPE = new Async::Interrupt::EventPipe;
		107	$SIGPIPE_W = AnyEvent->io (
		108	fh => $SIGPIPE->fileno,
		109	poll => "r",
		110	cb => \&_signal_check,
		111	);
		112
		113	Then, for each signal to hook, create an Async::Interrupt object. The
		114	callback just sets a global variable, as we are only interested in
		115	synchronous signals (i.e. when the event loop polls), which is why the
		116	pipe draining is not done automatically.
		117
		118	my $interrupt = new Async::Interrupt
		119	cb => sub { undef $SIGNAL_RECEIVED{$signum} }
		120	signal => $signal,
		121	pipe => [$SIGPIPE_R->filenos],
		122	pipe_autodrain => 0,
		123	;
		124
		125	Finally, the I/O callback for the event pipe handles the signals:
		126
		127	sub _signal_check {
		128	# drain the pipe first
		129	$SIGPIPE->drain;
		130
		131	# two loops, just to be sure
		132	while (%SIGNAL_RECEIVED) {
		133	for (keys %SIGNAL_RECEIVED) {
		134	delete $SIGNAL_RECEIVED{$_};
		135	warn "signal $_ received\n";
		136	}
		137	}
		138	}
		139
		140
		141
		142	=head1 THE Async::Interrupt CLASS
43		143
44	=over 4	144	=over 4
45		145
46	=cut	146	=cut
47		147
48	package Async::Interrupt;	148	package Async::Interrupt;
49		149
50	no warnings;	150	use common::sense;
51		151
52	BEGIN {	152	BEGIN {
		153	# the next line forces initialisation of internal
		154	# signal handling # variables
		155	$SIG{KILL} = sub { };
		156
53	$VERSION = '0.02';	157	our $VERSION = '0.6';
54		158
55	require XSLoader;	159	require XSLoader;
56	XSLoader::load Async::Interrupt::, $VERSION;	160	XSLoader::load ("Async::Interrupt", $VERSION);
57	}	161	}
58		162
59	our $DIED = sub { warn "$@" };	163	our $DIED = sub { warn "$@" };
60		164
61	=item $async = new Async::Interrupt key => value...	165	=item $async = new Async::Interrupt key => value...
…		…
99	C<$value> is the C<value> passed to some earlier call to either C<$signal>	203	C<$value> is the C<value> passed to some earlier call to either C<$signal>
100	or the C<signal_func> function.	204	or the C<signal_func> function.
101		205
102	Note that, because the callback can be invoked at almost any time, you	206	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	207	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	208	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,	209	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	210	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).	211	which case the requirements set out for C<cb> apply as well).
		212
		213	=item var => $scalar_ref
		214
		215	When specified, then the given argument must be a reference to a
		216	scalar. The scalar will be set to C<0> initially. Signalling the interrupt
		217	object will set it to the passed value, handling the interrupt will reset
		218	it to C<0> again.
		219
		220	Note that the only thing you are legally allowed to do is to is to check
		221	the variable in a boolean or integer context (e.g. comparing it with a
		222	string, or printing it, will I<destroy> it and might cause your program to
		223	crash or worse).
		224
		225	=item signal => $signame_or_value
		226
		227	When this parameter is specified, then the Async::Interrupt will hook the
		228	given signal, that is, it will effectively call C<< ->signal (0) >> each time
		229	the given signal is caught by the process.
		230
		231	Only one async can hook a given signal, and the signal will be restored to
		232	defaults when the Async::Interrupt object gets destroyed.
108		233
109	=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]	234	=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
110		235
111	Specifies two file descriptors (or file handles) that should be signalled	236	Specifies two file descriptors (or file handles) that should be signalled
112	whenever the async interrupt is signalled. This means a single octet will	237	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	238	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	239	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	240	are written. It is required that the file handles are both in nonblocking
116	mode.	241	mode.
117		242
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.	243	The object will keep a reference to the file handles.
122		244
123	This can be used to ensure that async notifications will interrupt event	245	This can be used to ensure that async notifications will interrupt event
124	frameworks as well.	246	frameworks as well.
125		247
		248	Note that C<Async::Interrupt> will create a suitable signal fd
		249	automatically when your program requests one, so you don't have to specify
		250	this argument when all you want is an extra file descriptor to watch.
		251
		252	If you want to share a single event pipe between multiple Async::Interrupt
		253	objects, you can use the C<Async::Interrupt::EventPipe> class to manage
		254	those.
		255
126	=back	256	=back
127		257
128	=cut	258	=cut
129		259
130	sub new {	260	sub new {
131	my ($class, %arg) = @_;	261	my ($class, %arg) = @_;
132		262
133	bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1]), $class	263	bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class
134	}	264	}
135		265
136	=item ($signal_func, $signal_arg) = $async->signal_func	266	=item ($signal_func, $signal_arg) = $async->signal_func
137		267
138	Returns the address of a function to call asynchronously. The function has	268	Returns the address of a function to call asynchronously. The function
139	the following prototype and needs to be passed the specified C<$c_arg>,	269	has the following prototype and needs to be passed the specified
140	which is a C<void *> cast to C<IV>:	270	C<$signal_arg>, which is a C<void *> cast to C<IV>:
141		271
142	void (signal_func) (void signal_arg, int value)	272	void (signal_func) (void signal_arg, int value)
143		273
144	An example call would look like:	274	An example call would look like:
145		275
146	signal_func (signal_arg, 0);	276	signal_func (signal_arg, 0);
147		277
148	The function is safe to call from within signal and thread contexts, at	278	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.	279	any time. The specified C<value> is passed to both C and Perl callback.
150		280
151	C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is	281	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
152	portable).	282	(1..127 is portable).
153		283
154	If the function is called while the Async::Interrupt object is already	284	If the function is called while the Async::Interrupt object is already
155	signaled but before the callbacks are being executed, then the stored	285	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	286	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	287	nature of the code, the C<value> can even be passed to two consecutive
158	invocations of the callback.	288	invocations of the callback.
159		289
		290	=item $address = $async->c_var
		291
		292	Returns the address (cast to IV) of an C<IV> variable. The variable is set
		293	to C<0> initially and gets set to the passed value whenever the object
		294	gets signalled, and reset to C<0> once the interrupt has been handled.
		295
		296	Note that it is often beneficial to just call C<PERL_ASYNC_CHECK ()> to
		297	handle any interrupts.
		298
		299	Example: call some XS function to store the address, then show C code
		300	waiting for it.
		301
		302	my_xs_func $async->c_var;
		303
		304	static IV *valuep;
		305
		306	void
		307	my_xs_func (void *addr)
		308	CODE:
		309	valuep = (IV *)addr;
		310
		311	// code in a loop, waiting
		312	while (!*valuep)
		313	; // do something
		314
160	=item $async->signal ($value=0)	315	=item $async->signal ($value=1)
161		316
162	This signals the given async object from Perl code. Semi-obviously, this	317	This signals the given async object from Perl code. Semi-obviously, this
163	will instantly trigger the callback invocation.	318	will instantly trigger the callback invocation (it does not, as the name
		319	might imply, do anything with POSIX signals).
164		320
165	C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is	321	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
166	portable).	322	(1..127 is portable).
		323
		324	=item $async->signal_hysteresis ($enable)
		325
		326	Enables or disables signal hysteresis (default: disabled). If a POSIX
		327	signal is used as a signal source for the interrupt object, then enabling
		328	signal hysteresis causes Async::Interrupt to reset the signal action to
		329	C<SIG_IGN> in the signal handler and restore it just before handling the
		330	interruption.
		331
		332	When you expect a lot of signals (e.g. when using SIGIO), then enabling
		333	signal hysteresis can reduce the number of handler invocations
		334	considerably, at the cost of two extra syscalls.
		335
		336	Note that setting the signal to C<SIG_IGN> can have unintended side
		337	effects when you fork and exec other programs, as often they do nto expect
		338	signals to be ignored by default.
167		339
168	=item $async->block	340	=item $async->block
169		341
170	Sometimes you need a "critical section" of code where
171
172	=item $async->unblock	342	=item $async->unblock
173		343
		344	Sometimes you need a "critical section" of code that will not be
		345	interrupted by an Async::Interrupt. This can be implemented by calling C<<
		346	$async->block >> before the critical section, and C<< $async->unblock >>
		347	afterwards.
		348
		349	Note that there must be exactly one call of C<unblock> for every previous
		350	call to C<block> (i.e. calls can nest).
		351
		352	Since ensuring this in the presence of exceptions and threads is
		353	usually more difficult than you imagine, I recommend using C<<
		354	$async->scoped_block >> instead.
		355
		356	=item $async->scope_block
		357
		358	This call C<< $async->block >> and installs a handler that is called when
		359	the current scope is exited (via an exception, by canceling the Coro
		360	thread, by calling last/goto etc.).
		361
		362	This is the recommended (and fastest) way to implement critical sections.
		363
		364	=item ($block_func, $block_arg) = $async->scope_block_func
		365
		366	Returns the address of a function that implements the C<scope_block>
		367	functionality.
		368
		369	It has the following prototype and needs to be passed the specified
		370	C<$block_arg>, which is a C<void *> cast to C<IV>:
		371
		372	void (block_func) (void block_arg)
		373
		374	An example call would look like:
		375
		376	block_func (block_arg);
		377
		378	The function is safe to call only from within the toplevel of a perl XS
		379	function and will call C<LEAVE> and C<ENTER> (in this order!).
		380
		381	=item $async->pipe_enable
		382
		383	=item $async->pipe_disable
		384
		385	Enable/disable signalling the pipe when the interrupt occurs (default is
		386	enabled). Writing to a pipe is relatively expensive, so it can be disabled
		387	when you know you are not waiting for it (for example, with L<EV> you
		388	could disable the pipe in a check watcher, and enable it in a prepare
		389	watcher).
		390
		391	Note that currently, while C<pipe_disable> is in effect, no attempt to
		392	read from the pipe will be done when handling events. This might change as
		393	soon as I realize why this is a mistake.
		394
		395	=item $fileno = $async->pipe_fileno
		396
		397	Returns the reading side of the signalling pipe. If no signalling pipe is
		398	currently attached to the object, it will dynamically create one.
		399
		400	Note that the only valid oepration on this file descriptor is to wait
		401	until it is readable. The fd might belong currently to a pipe, a tcp
		402	socket, or an eventfd, depending on the platform, and is guaranteed to be
		403	C<select>able.
		404
		405	=item $async->pipe_autodrain ($enable)
		406
		407	Enables (C<1>) or disables (C<0>) automatic draining of the pipe (default:
		408	enabled). When automatic draining is enabled, then Async::Interrupt will
		409	automatically clear the pipe. Otherwise the user is responsible for this
		410	draining.
		411
		412	This is useful when you want to share one pipe among many Async::Interrupt
		413	objects.
		414
		415	=item $async->post_fork
		416
		417	The object will not normally be usable after a fork (as the pipe fd is
		418	shared between processes). Calling this method after a fork in the child
		419	ensures that the object will work as expected again. It only needs to be
		420	called when the async object is used in the child.
		421
		422	This only works when the pipe was created by Async::Interrupt.
		423
		424	Async::Interrupt ensures that the reading file descriptor does not change
		425	it's value.
		426
		427	=item $signum = Async::Interrupt::sig2num $signame_or_number
		428
		429	=item $signame = Async::Interrupt::sig2name $signame_or_number
		430
		431	These two convenience functions simply convert a signal name or number to
		432	the corresponding name or number. They are not used by this module and
		433	exist just because perl doesn't have a nice way to do this on its own.
		434
		435	They will return C<undef> on illegal names or numbers.
		436
		437	=back
		438
		439	=head1 THE Async::Interrupt::EventPipe CLASS
		440
		441	Pipes are the predominent utility to make asynchronous signals
		442	synchronous. However, pipes are hard to come by: they don't exist on the
		443	broken windows platform, and on GNU/Linux systems, you might want to use
		444	an C<eventfd> instead.
		445
		446	This class creates selectable event pipes in a portable fashion: on
		447	windows, it will try to create a tcp socket pair, on GNU/Linux, it will
		448	try to create an eventfd and everywhere else it will try to use a normal
		449	pipe.
		450
		451	=over 4
		452
		453	=item $epipe = new Async::Interrupt::EventPipe
		454
		455	This creates and returns an eventpipe object. This object is simply a
		456	blessed array reference:
		457
		458	=item ($r_fd, $w_fd) = $epipe->filenos
		459
		460	Returns the read-side file descriptor and the write-side file descriptor.
		461
		462	Example: pass an eventpipe object as pipe to the Async::Interrupt
		463	constructor, and create an AnyEvent watcher for the read side.
		464
		465	my $epipe = new Async::Interrupt::EventPipe;
		466	my $asy = new Async::Interrupt pipe => [$epipe->filenos];
		467	my $iow = AnyEvent->io (fh => $epipe->fileno, poll => 'r', cb => sub { });
		468
		469	=item $r_fd = $epipe->fileno
		470
		471	Return only the reading/listening side.
		472
		473	=item $epipe->signal
		474
		475	Write something to the pipe, in a portable fashion.
		476
		477	=item $epipe->drain
		478
		479	Drain (empty) the pipe.
		480
		481	=item $epipe->renew
		482
		483	Recreates the pipe (useful after a fork). The reading side will not change
		484	it's file descriptor number, but the writing side might.
		485
		486	=back
		487
174	=cut	488	=cut
175		489
176	1;	490	1;
177		491
178	=back
179
180	=head1 EXAMPLE	492	=head1 EXAMPLE
181		493
182	#TODO	494	There really should be a complete C/XS example. Bug me about it. Better
		495	yet, create one.
183		496
184	=head1 IMPLEMENTATION DETAILS AND LIMITATIONS	497	=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
185		498
186	This module works by "hijacking" SIGKILL, which is guarenteed to be always	499	This module works by "hijacking" SIGKILL, which is guaranteed to always
187	available in perl, but also cannot be caught, so is always available.	500	exist, but also cannot be caught, so is always available.
188		501
189	Basically, this module fakes the receive of a SIGKILL signal and	502	Basically, this module fakes the occurance of a SIGKILL signal and
190	then catches it. This makes normal signal handling slower (probably	503	then intercepts the interpreter handling it. This makes normal signal
191	unmeasurably), but has the advantage of not requiring a special runops nor	504	handling slower (probably unmeasurably, though), but has the advantage
192	slowing down normal perl execution a bit.	505	of not requiring a special runops function, nor slowing down normal perl
		506	execution a bit.
193		507
194	It assumes that C<sig_atomic_t> and C<int> are both exception-safe to	508	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	509	modify.
196	C<int>, so we can assume that this is quite portbale, at least w.r.t.
197	signals).
198		510
199	=head1 AUTHOR	511	=head1 AUTHOR
200		512
201	Marc Lehmann <schmorp@schmorp.de>	513	Marc Lehmann <schmorp@schmorp.de>
202	http://home.schmorp.de/	514	http://home.schmorp.de/

Diff Legend

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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents): Revision 1.2 by root, Thu Jul 2 15:13:03 2009 UTC vs. Revision 1.18 by root, Tue Jul 28 12:50:16 2009 UTC

Diff Legend

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.2 by root, Thu Jul 2 15:13:03 2009 UTC vs.
Revision 1.18 by root, Tue Jul 28 12:50:16 2009 UTC