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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.17 by root, Tue Jul 28 01:19:44 2009 UTC vs.
Revision 1.30 by root, Tue Apr 24 22:01:59 2012 UTC

…		…
91	I<running> interpreter, there is optional support for signalling a pipe	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	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>	93	L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
94	and C<write> syscall.	94	and C<write> syscall.
95		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	On the Perl level, a new loop object (which contains the thread)
		146	is created, by first calling some XS constructor, querying the
		147	C-level callback function and feeding that as the C<c_cb> into the
		148	Async::Interrupt constructor:
		149
		150	my $self = XS_thread_constructor;
		151	my ($c_func, $c_arg) = _c_func $self; # return the c callback
		152	my $asy = new Async::Interrupt c_cb => [$c_func, $c_arg];
		153
		154	Then the newly created Interrupt object is queried for the signaling
		155	function that the newly created thread should call, and this is in turn
		156	told to the thread object:
		157
		158	_attach $self, $asy->signal_func;
		159
		160	So to repeat: first the XS object is created, then it is queried for the
		161	callback that should be called when the Interrupt object gets signalled.
		162
		163	Then the interrupt object is queried for the callback fucntion that the
		164	thread should call to signal the Interrupt object, and this callback is
		165	then attached to the thread.
		166
		167	You have to be careful that your new thread is not signalling before the
		168	signal function was configured, for example by starting the background
		169	thread only within C<_attach>.
		170
		171	That concludes the Perl part.
		172
		173	The XS part consists of the actual constructor which creates a thread,
		174	which is not relevant for this example, and two functions, C<_c_func>,
		175	which returns the Perl-side callback, and C<_attach>, which configures
		176	the signalling functioon that is safe toc all from another thread. For
		177	simplicity, we will use global variables to store the functions, normally
		178	you would somehow attach them to C<$self>.
		179
		180	The C<c_func> simply returns the address of a static function and arranges
		181	for the object pointed to by C<$self> to be passed to it, as an integer:
		182
		183	void
		184	_c_func (SV *loop)
		185	PPCODE:
		186	EXTEND (SP, 2);
		187	PUSHs (sv_2mortal (newSViv (PTR2IV (c_func))));
		188	PUSHs (sv_2mortal (newSViv (SvRV (loop))));
		189
		190	This would be the callback (since it runs in a normal Perl context, it is
		191	permissible to manipulate Perl values):
		192
		193	static void
		194	c_func (pTHX_ void *loop_, int value)
		195	{
		196	SV loop_object = (SV )loop_;
		197	...
		198	}
		199
		200	And this attaches the signalling callback:
		201
		202	static void (my_sig_func) (void signal_arg, int value);
		203	static void *my_sig_arg;
		204
		205	void
		206	_attach (SV loop_, IV sig_func, void sig_arg)
		207	CODE:
		208	{
		209	my_sig_func = sig_func;
		210	my_sig_arg = sig_arg;
		211
		212	/* now run the thread */
		213	thread_create (&u->tid, l_run, 0);
		214	}
		215
		216	And C<l_run> (the background thread) would eventually call the signaling
		217	function:
		218
		219	my_sig_func (my_sig_arg, 0);
		220
		221	You can have a look at L<EV::Loop::Async> for an actual example using
		222	intra-thread communication, locking and so on.
		223
		224
96	=head1 THE Async::Interrupt CLASS	225	=head1 THE Async::Interrupt CLASS
97		226
98	=over 4	227	=over 4
99		228
100	=cut	229	=cut
…		…
103		232
104	use common::sense;	233	use common::sense;
105		234
106	BEGIN {	235	BEGIN {
107	# the next line forces initialisation of internal	236	# the next line forces initialisation of internal
108	# signal handling # variables	237	# signal handling variables, otherwise, PL_sig_pending
		238	# etc. might be null pointers.
109	$SIG{KILL} = sub { };	239	$SIG{KILL} = sub { };
110		240
111	our $VERSION = '0.6';	241	our $VERSION = '1.05';
112		242
113	require XSLoader;	243	require XSLoader;
114	XSLoader::load ("Async::Interrupt", $VERSION);	244	XSLoader::load ("Async::Interrupt", $VERSION);
115	}	245	}
116		246
…		…
139	The exceptions are C<$!> and C<$@>, which are saved and restored by	269	The exceptions are C<$!> and C<$@>, which are saved and restored by
140	Async::Interrupt.	270	Async::Interrupt.
141		271
142	If the callback should throw an exception, then it will be caught,	272	If the callback should throw an exception, then it will be caught,
143	and C<$Async::Interrupt::DIED> will be called with C<$@> containing	273	and C<$Async::Interrupt::DIED> will be called with C<$@> containing
144	the exception. The default will simply C<warn> about the message and	274	the exception. The default will simply C<warn> about the message and
145	continue.	275	continue.
146		276
147	=item c_cb => [$c_func, $c_arg]	277	=item c_cb => [$c_func, $c_arg]
148		278
149	Registers a C callback the be invoked whenever the async interrupt is	279	Registers a C callback the be invoked whenever the async interrupt is
…		…
183	the given signal is caught by the process.	313	the given signal is caught by the process.
184		314
185	Only one async can hook a given signal, and the signal will be restored to	315	Only one async can hook a given signal, and the signal will be restored to
186	defaults when the Async::Interrupt object gets destroyed.	316	defaults when the Async::Interrupt object gets destroyed.
187		317
		318	=item signal_hysteresis => $boolean
		319
		320	Sets the initial signal hysteresis state, see the C<signal_hysteresis>
		321	method, below.
		322
188	=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]	323	=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
189		324
190	Specifies two file descriptors (or file handles) that should be signalled	325	Specifies two file descriptors (or file handles) that should be signalled
191	whenever the async interrupt is signalled. This means a single octet will	326	whenever the async interrupt is signalled. This means a single octet will
192	be written to it, and before the callback is being invoked, it will be	327	be written to it, and before the callback is being invoked, it will be
…		…
205		340
206	If you want to share a single event pipe between multiple Async::Interrupt	341	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	342	objects, you can use the C<Async::Interrupt::EventPipe> class to manage
208	those.	343	those.
209		344
		345	=item pipe_autodrain => $boolean
		346
		347	Sets the initial autodrain state, see the C<pipe_autodrain> method, below.
		348
210	=back	349	=back
211		350
212	=cut	351	=cut
213		352
214	sub new {	353	sub new {
215	my ($class, %arg) = @_;	354	my ($class, %arg) = @_;
216		355
217	bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class	356	my $self = bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class;
		357
		358	# urgs, reminds me of Event
		359	for my $attr (qw(pipe_autodrain signal_hysteresis)) {
		360	$self->$attr ($arg{$attr}) if exists $arg{$attr};
		361	}
		362
		363	$self
218	}	364	}
219		365
220	=item ($signal_func, $signal_arg) = $async->signal_func	366	=item ($signal_func, $signal_arg) = $async->signal_func
221		367
222	Returns the address of a function to call asynchronously. The function	368	Returns the address of a function to call asynchronously. The function
…		…
273	might imply, do anything with POSIX signals).	419	might imply, do anything with POSIX signals).
274		420
275	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>	421	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
276	(1..127 is portable).	422	(1..127 is portable).
277		423
		424	=item $async->handle
		425
		426	Calls the callback if the object is pending.
		427
		428	This method does not need to be called normally, as it will be invoked
		429	automatically. However, it can be used to force handling of outstanding
		430	interrupts while the object is blocked.
		431
		432	One reason why one might want to do that is when you want to switch
		433	from asynchronous interruptions to synchronous one, using e.g. an event
		434	loop. To do that, one would first C<< $async->block >> the interrupt
		435	object, then register a read watcher on the C<pipe_fileno> that calls C<<
		436	$async->handle >>.
		437
		438	This disables asynchronous interruptions, but ensures that interrupts are
		439	handled by the event loop.
		440
278	=item $async->signal_hysteresis ($enable)	441	=item $async->signal_hysteresis ($enable)
279		442
280	Enables or disables signal hysteresis (default: disabled). If a POSIX	443	Enables or disables signal hysteresis (default: disabled). If a POSIX
281	signal is used as a signal source for the interrupt object, then enabling	444	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	445	signal hysteresis causes Async::Interrupt to reset the signal action to
…		…
286	When you expect a lot of signals (e.g. when using SIGIO), then enabling	449	When you expect a lot of signals (e.g. when using SIGIO), then enabling
287	signal hysteresis can reduce the number of handler invocations	450	signal hysteresis can reduce the number of handler invocations
288	considerably, at the cost of two extra syscalls.	451	considerably, at the cost of two extra syscalls.
289		452
290	Note that setting the signal to C<SIG_IGN> can have unintended side	453	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	454	effects when you fork and exec other programs, as often they do not expect
292	signals to be ignored by default.	455	signals to be ignored by default.
293		456
294	=item $async->block	457	=item $async->block
295		458
296	=item $async->unblock	459	=item $async->unblock
…		…
349	=item $fileno = $async->pipe_fileno	512	=item $fileno = $async->pipe_fileno
350		513
351	Returns the reading side of the signalling pipe. If no signalling pipe is	514	Returns the reading side of the signalling pipe. If no signalling pipe is
352	currently attached to the object, it will dynamically create one.	515	currently attached to the object, it will dynamically create one.
353		516
354	Note that the only valid oepration on this file descriptor is to wait	517	Note that the only valid operation on this file descriptor is to wait
355	until it is readable. The fd might belong currently to a pipe, a tcp	518	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	519	socket, or an eventfd, depending on the platform, and is guaranteed to be
357	C<select>able.	520	C<select>able.
358		521
359	=item $async->pipe_autodrain ($enable)	522	=item $async->pipe_autodrain ($enable)
…		…
364	draining.	527	draining.
365		528
366	This is useful when you want to share one pipe among many Async::Interrupt	529	This is useful when you want to share one pipe among many Async::Interrupt
367	objects.	530	objects.
368		531
		532	=item $async->pipe_drain
		533
		534	Drains the pipe manually, for example, when autodrain is disabled. Does
		535	nothing when no pipe is enabled.
		536
369	=item $async->post_fork	537	=item $async->post_fork
370		538
371	The object will not normally be usable after a fork (as the pipe fd is	539	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	540	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	541	ensures that the object will work as expected again. It only needs to be
…		…
376	This only works when the pipe was created by Async::Interrupt.	544	This only works when the pipe was created by Async::Interrupt.
377		545
378	Async::Interrupt ensures that the reading file descriptor does not change	546	Async::Interrupt ensures that the reading file descriptor does not change
379	it's value.	547	it's value.
380		548
		549	=item $signum = Async::Interrupt::sig2num $signame_or_number
		550
		551	=item $signame = Async::Interrupt::sig2name $signame_or_number
		552
		553	These two convenience functions simply convert a signal name or number to
		554	the corresponding name or number. They are not used by this module and
		555	exist just because perl doesn't have a nice way to do this on its own.
		556
		557	They will return C<undef> on illegal names or numbers.
		558
381	=back	559	=back
382		560
383	=head1 THE Async::Interrupt::EventPipe CLASS	561	=head1 THE Async::Interrupt::EventPipe CLASS
384		562
385	Pipes are the predominent utility to make asynchronous signals	563	Pipes are the predominant utility to make asynchronous signals
386	synchronous. However, pipes are hard to come by: they don't exist on the	564	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	565	broken windows platform, and on GNU/Linux systems, you might want to use
388	an C<eventfd> instead.	566	an C<eventfd> instead.
389		567
390	This class creates selectable event pipes in a portable fashion: on	568	This class creates selectable event pipes in a portable fashion: on
…		…
420		598
421	=item $epipe->drain	599	=item $epipe->drain
422		600
423	Drain (empty) the pipe.	601	Drain (empty) the pipe.
424		602
		603	=item ($c_func, $c_arg) = $epipe->signal_func
		604
		605	=item ($c_func, $c_arg) = $epipe->drain_func
		606
		607	These two methods returns a function pointer and C<void *> argument
		608	that can be called to have the effect of C<< $epipe->signal >> or C<<
		609	$epipe->drain >>, respectively, on the XS level.
		610
		611	They both have the following prototype and need to be passed their
		612	C<$c_arg>, which is a C<void *> cast to an C<IV>:
		613
		614	void (c_func) (void c_arg)
		615
		616	An example call would look like:
		617
		618	c_func (c_arg);
		619
425	=item $epipe->renew	620	=item $epipe->renew
426		621
427	Recreates the pipe (useful after a fork). The reading side will not change	622	Recreates the pipe (useful after a fork). The reading side will not change
428	it's file descriptor number, but the writing side might.	623	it's file descriptor number, but the writing side might.
429		624
		625	=item $epipe->wait
		626
		627	This method blocks the process until there are events on the pipe. This is
		628	not a very event-based or ncie way of usign an event pipe, but it can be
		629	occasionally useful.
		630
430	=back	631	=back
431		632
432	=cut	633	=cut
433		634
434	1;	635	1;
435
436	=head1 EXAMPLE
437
438	There really should be a complete C/XS example. Bug me about it. Better
439	yet, create one.
440		636
441	=head1 IMPLEMENTATION DETAILS AND LIMITATIONS	637	=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
442		638
443	This module works by "hijacking" SIGKILL, which is guaranteed to always	639	This module works by "hijacking" SIGKILL, which is guaranteed to always
444	exist, but also cannot be caught, so is always available.	640	exist, but also cannot be caught, so is always available.

Diff Legend

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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents): Revision 1.17 by root, Tue Jul 28 01:19:44 2009 UTC vs. Revision 1.30 by root, Tue Apr 24 22:01:59 2012 UTC

Diff Legend

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.17 by root, Tue Jul 28 01:19:44 2009 UTC vs.
Revision 1.30 by root, Tue Apr 24 22:01:59 2012 UTC