[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.19 by root, Tue Jul 28 13:17:05 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 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
		148
93	=over 4	149	=over 4
94		150
95	=cut	151	=cut
96		152
97	package Async::Interrupt;	153	package Async::Interrupt;
98		154
99	use common::sense;	155	use common::sense;
100		156
101	BEGIN {	157	BEGIN {
102	# the next line forces initialisation of internal	158	# the next line forces initialisation of internal
103	# signal handling # variables	159	# signal handling variables, otherwise, PL_sig_pending
		160	# etc. will be null pointers.
104	$SIG{KILL} = sub { };	161	$SIG{KILL} = sub { };
105		162
106	our $VERSION = '0.042';	163	our $VERSION = '1.0';
107		164
108	require XSLoader;	165	require XSLoader;
109	XSLoader::load ("Async::Interrupt", $VERSION);	166	XSLoader::load ("Async::Interrupt", $VERSION);
110	}	167	}
111		168
…		…
134	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
135	Async::Interrupt.	192	Async::Interrupt.
136		193
137	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,
138	and C<$Async::Interrupt::DIED> will be called with C<$@> containing	195	and C<$Async::Interrupt::DIED> will be called with C<$@> containing
139	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
140	continue.	197	continue.
141		198
142	=item c_cb => [$c_func, $c_arg]	199	=item c_cb => [$c_func, $c_arg]
143		200
144	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
…		…
160	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).
161		218
162	=item var => $scalar_ref	219	=item var => $scalar_ref
163		220
164	When specified, then the given argument must be a reference to a	221	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	222	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	223	object will set it to the passed value, handling the interrupt will reset
167	it to C<0> again.	224	it to C<0> again.
168		225
169	Note that the only thing you are legally allowed to do is to is to check	226	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	227	the variable in a boolean or integer context (e.g. comparing it with a
…		…
177	given signal, that is, it will effectively call C<< ->signal (0) >> each time	234	given signal, that is, it will effectively call C<< ->signal (0) >> each time
178	the given signal is caught by the process.	235	the given signal is caught by the process.
179		236
180	Only one async can hook a given signal, and the signal will be restored to	237	Only one async can hook a given signal, and the signal will be restored to
181	defaults when the Async::Interrupt object gets destroyed.	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.
182		244
183	=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]
184		246
185	Specifies two file descriptors (or file handles) that should be signalled	247	Specifies two file descriptors (or file handles) that should be signalled
186	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
…		…
194	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
195	frameworks as well.	257	frameworks as well.
196		258
197	Note that C<Async::Interrupt> will create a suitable signal fd	259	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	260	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.	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.
200		270
201	=back	271	=back
202		272
203	=cut	273	=cut
204		274
205	sub new {	275	sub new {
206	my ($class, %arg) = @_;	276	my ($class, %arg) = @_;
207		277
208	bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $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
209	}	286	}
210		287
211	=item ($signal_func, $signal_arg) = $async->signal_func	288	=item ($signal_func, $signal_arg) = $async->signal_func
212		289
213	Returns the address of a function to call asynchronously. The function has	290	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>,	291	has the following prototype and needs to be passed the specified
215	which is a C<void *> cast to C<IV>:	292	C<$signal_arg>, which is a C<void *> cast to C<IV>:
216		293
217	void (signal_func) (void signal_arg, int value)	294	void (signal_func) (void signal_arg, int value)
218		295
219	An example call would look like:	296	An example call would look like:
220		297
…		…
253	CODE:	330	CODE:
254	valuep = (IV *)addr;	331	valuep = (IV *)addr;
255		332
256	// code in a loop, waiting	333	// code in a loop, waiting
257	while (!*valuep)	334	while (!*valuep)
258	; // do soemthing	335	; // do something
259		336
260	=item $async->signal ($value=1)	337	=item $async->signal ($value=1)
261		338
262	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
263	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).
264		342
265	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>	343	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
266	(1..127 is 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.
267		361
268	=item $async->block	362	=item $async->block
269		363
270	=item $async->unblock	364	=item $async->unblock
271		365
…		…
286	This call C<< $async->block >> and installs a handler that is called when	380	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	381	the current scope is exited (via an exception, by canceling the Coro
288	thread, by calling last/goto etc.).	382	thread, by calling last/goto etc.).
289		383
290	This is the recommended (and fastest) way to implement critical sections.	384	This is the recommended (and fastest) way to implement critical sections.
		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!).
291		402
292	=item $async->pipe_enable	403	=item $async->pipe_enable
293		404
294	=item $async->pipe_disable	405	=item $async->pipe_disable
295		406
…		…
311	Note that the only valid oepration on this file descriptor is to wait	422	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	423	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	424	socket, or an eventfd, depending on the platform, and is guaranteed to be
314	C<select>able.	425	C<select>able.
315		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
316	=item $async->post_fork	437	=item $async->post_fork
317		438
318	The object will not normally be usable after a fork (as the pipe fd is	439	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	440	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	441	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.	444	This only works when the pipe was created by Async::Interrupt.
324		445
325	Async::Interrupt ensures that the reading file descriptor does not change	446	Async::Interrupt ensures that the reading file descriptor does not change
326	it's value.	447	it's value.
327		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
328	=cut	510	=cut
329		511
330	1;	512	1;
331
332	=back
333		513
334	=head1 EXAMPLE	514	=head1 EXAMPLE
335		515
336	There really should be a complete C/XS example. Bug me about it. Better	516	There really should be a complete C/XS example. Bug me about it. Better
337	yet, create one.	517	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.19 by root, Tue Jul 28 13:17:05 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.19 by root, Tue Jul 28 13:17:05 2009 UTC