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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.4 by root, Thu Jul 2 16:15:52 2009 UTC vs.
Revision 1.19 by root, Tue Jul 28 13:17:05 2009 UTC

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

Diff Legend

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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents): Revision 1.4 by root, Thu Jul 2 16:15:52 2009 UTC vs. Revision 1.19 by root, Tue Jul 28 13:17:05 2009 UTC

Diff Legend

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.4 by root, Thu Jul 2 16:15:52 2009 UTC vs.
Revision 1.19 by root, Tue Jul 28 13:17:05 2009 UTC