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

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

Diff Legend

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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents): Revision 1.1 by root, Thu Jul 2 13:41:44 2009 UTC vs. Revision 1.17 by root, Tue Jul 28 01:19:44 2009 UTC

Diff Legend

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.1 by root, Thu Jul 2 13:41:44 2009 UTC vs.
Revision 1.17 by root, Tue Jul 28 01:19:44 2009 UTC