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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.13 by root, Fri Jul 17 01:51:32 2009 UTC vs.
Revision 1.18 by root, Tue Jul 28 12:50:16 2009 UTC

…		…
53		53
54	For example the deliantra game server uses a variant of this technique	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	55	to interrupt background processes regularly to send map updates to game
56	clients.	56	clients.
57		57
		58	Or L<EV::Loop::Async> uses an interrupt object to wake up perl when new
		59	events have arrived.
		60
58	L<IO::AIO> and L<BDB> could also use this to speed up result reporting.	61	L<IO::AIO> and L<BDB> could also use this to speed up result reporting.
59		62
60	=item Speedy event loop invocation	63	=item Speedy event loop invocation
61		64
62	One could use this module e.g. in L<Coro> to interrupt a running coro-thread	65	One could use this module e.g. in L<Coro> to interrupt a running coro-thread
…		…
88	I<running> interpreter, there is optional support for signalling a pipe	91	I<running> interpreter, there is optional support for signalling a pipe
89	- that means you can also wait for the pipe to become readable (e.g. via	92	- 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>	93	L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
91	and C<write> syscall.	94	and C<write> syscall.
92		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
		143
93	=over 4	144	=over 4
94		145
95	=cut	146	=cut
96		147
97	package Async::Interrupt;	148	package Async::Interrupt;
…		…
101	BEGIN {	152	BEGIN {
102	# the next line forces initialisation of internal	153	# the next line forces initialisation of internal
103	# signal handling # variables	154	# signal handling # variables
104	$SIG{KILL} = sub { };	155	$SIG{KILL} = sub { };
105		156
106	our $VERSION = '0.042';	157	our $VERSION = '0.6';
107		158
108	require XSLoader;	159	require XSLoader;
109	XSLoader::load ("Async::Interrupt", $VERSION);	160	XSLoader::load ("Async::Interrupt", $VERSION);
110	}	161	}
111		162
…		…
160	which case the requirements set out for C<cb> apply as well).	211	which case the requirements set out for C<cb> apply as well).
161		212
162	=item var => $scalar_ref	213	=item var => $scalar_ref
163		214
164	When specified, then the given argument must be a reference to a	215	When specified, then the given argument must be a reference to a
165	scalar. The scalar will be set to C<0> intiially. Signalling the interrupt	216	scalar. The scalar will be set to C<0> initially. Signalling the interrupt
166	object will set it to the passed value, handling the interrupt will reset	217	object will set it to the passed value, handling the interrupt will reset
167	it to C<0> again.	218	it to C<0> again.
168		219
169	Note that the only thing you are legally allowed to do is to is to check	220	Note that the only thing you are legally allowed to do is to is to check
170	the variable in a boolean or integer context (e.g. comparing it with a	221	the variable in a boolean or integer context (e.g. comparing it with a
…		…
194	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
195	frameworks as well.	246	frameworks as well.
196		247
197	Note that C<Async::Interrupt> will create a suitable signal fd	248	Note that C<Async::Interrupt> will create a suitable signal fd
198	automatically when your program requests one, so you don't have to specify	249	automatically when your program requests one, so you don't have to specify
199	this agrument when all you want is an extra file descriptor to watch.	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.
200		255
201	=back	256	=back
202		257
203	=cut	258	=cut
204		259
…		…
208	bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class	263	bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class
209	}	264	}
210		265
211	=item ($signal_func, $signal_arg) = $async->signal_func	266	=item ($signal_func, $signal_arg) = $async->signal_func
212		267
213	Returns the address of a function to call asynchronously. The function has	268	Returns the address of a function to call asynchronously. The function
214	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
215	which is a C<void *> cast to C<IV>:	270	C<$signal_arg>, which is a C<void *> cast to C<IV>:
216		271
217	void (signal_func) (void signal_arg, int value)	272	void (signal_func) (void signal_arg, int value)
218		273
219	An example call would look like:	274	An example call would look like:
220		275
…		…
253	CODE:	308	CODE:
254	valuep = (IV *)addr;	309	valuep = (IV *)addr;
255		310
256	// code in a loop, waiting	311	// code in a loop, waiting
257	while (!*valuep)	312	while (!*valuep)
258	; // do soemthing	313	; // do something
259		314
260	=item $async->signal ($value=1)	315	=item $async->signal ($value=1)
261		316
262	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
263	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).
264		320
265	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>	321	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
266	(1..127 is 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.
267		339
268	=item $async->block	340	=item $async->block
269		341
270	=item $async->unblock	342	=item $async->unblock
271		343
…		…
286	This call C<< $async->block >> and installs a handler that is called when	358	This call C<< $async->block >> and installs a handler that is called when
287	the current scope is exited (via an exception, by canceling the Coro	359	the current scope is exited (via an exception, by canceling the Coro
288	thread, by calling last/goto etc.).	360	thread, by calling last/goto etc.).
289		361
290	This is the recommended (and fastest) way to implement critical sections.	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!).
291		380
292	=item $async->pipe_enable	381	=item $async->pipe_enable
293		382
294	=item $async->pipe_disable	383	=item $async->pipe_disable
295		384
…		…
311	Note that the only valid oepration on this file descriptor is to wait	400	Note that the only valid oepration on this file descriptor is to wait
312	until it is readable. The fd might belong currently to a pipe, a tcp	401	until it is readable. The fd might belong currently to a pipe, a tcp
313	socket, or an eventfd, depending on the platform, and is guaranteed to be	402	socket, or an eventfd, depending on the platform, and is guaranteed to be
314	C<select>able.	403	C<select>able.
315		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
316	=item $async->post_fork	415	=item $async->post_fork
317		416
318	The object will not normally be usable after a fork (as the pipe fd is	417	The object will not normally be usable after a fork (as the pipe fd is
319	shared between processes). Calling this method after a fork in the child	418	shared between processes). Calling this method after a fork in the child
320	ensures that the object will work as expected again. It only needs to be	419	ensures that the object will work as expected again. It only needs to be
…		…
323	This only works when the pipe was created by Async::Interrupt.	422	This only works when the pipe was created by Async::Interrupt.
324		423
325	Async::Interrupt ensures that the reading file descriptor does not change	424	Async::Interrupt ensures that the reading file descriptor does not change
326	it's value.	425	it's value.
327		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
328	=cut	488	=cut
329		489
330	1;	490	1;
331
332	=back
333		491
334	=head1 EXAMPLE	492	=head1 EXAMPLE
335		493
336	There really should be a complete C/XS example. Bug me about it. Better	494	There really should be a complete C/XS example. Bug me about it. Better
337	yet, create one.	495	yet, create one.

Diff Legend

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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents): Revision 1.13 by root, Fri Jul 17 01:51:32 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.13 by root, Fri Jul 17 01:51:32 2009 UTC vs.
Revision 1.18 by root, Tue Jul 28 12:50:16 2009 UTC