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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.19 by root, Tue Jul 28 13:17:05 2009 UTC vs.
Revision 1.33 by root, Fri Apr 11 04:24:47 2014 UTC

…		…
114	callback just sets a global variable, as we are only interested in	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	115	synchronous signals (i.e. when the event loop polls), which is why the
116	pipe draining is not done automatically.	116	pipe draining is not done automatically.
117		117
118	my $interrupt = new Async::Interrupt	118	my $interrupt = new Async::Interrupt
119	cb => sub { undef $SIGNAL_RECEIVED{$signum} }	119	cb => sub { undef $SIGNAL_RECEIVED{$signum} },
120	signal => $signum,	120	signal => $signum,
121	pipe => [$SIGPIPE->filenos],	121	pipe => [$SIGPIPE->filenos],
122	pipe_autodrain => 0,	122	pipe_autodrain => 0,
123	;	123	;
124		124
…		…
140	=head2 Interrupt perl from another thread	140	=head2 Interrupt perl from another thread
141		141
142	This example interrupts the Perl interpreter from another thread, via the	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.	143	XS API. This is used by e.g. the L<EV::Loop::Async> module.
144		144
145	#TODO#	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
146		224
147	=head1 THE Async::Interrupt CLASS	225	=head1 THE Async::Interrupt CLASS
148		226
149	=over 4	227	=over 4
150		228
…		…
155	use common::sense;	233	use common::sense;
156		234
157	BEGIN {	235	BEGIN {
158	# the next line forces initialisation of internal	236	# the next line forces initialisation of internal
159	# signal handling variables, otherwise, PL_sig_pending	237	# signal handling variables, otherwise, PL_sig_pending
160	# etc. will be null pointers.	238	# etc. might be null pointers.
161	$SIG{KILL} = sub { };	239	$SIG{KILL} = sub { };
162		240
163	our $VERSION = '1.0';	241	our $VERSION = '1.2';
164		242
165	require XSLoader;	243	require XSLoader;
166	XSLoader::load ("Async::Interrupt", $VERSION);	244	XSLoader::load ("Async::Interrupt", $VERSION);
167	}	245	}
168		246
…		…
341	might imply, do anything with POSIX signals).	419	might imply, do anything with POSIX signals).
342		420
343	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>
344	(1..127 is portable).	422	(1..127 is portable).
345		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
346	=item $async->signal_hysteresis ($enable)	441	=item $async->signal_hysteresis ($enable)
347		442
348	Enables or disables signal hysteresis (default: disabled). If a POSIX	443	Enables or disables signal hysteresis (default: disabled). If a POSIX
349	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
350	signal hysteresis causes Async::Interrupt to reset the signal action to	445	signal hysteresis causes Async::Interrupt to reset the signal action to
…		…
354	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
355	signal hysteresis can reduce the number of handler invocations	450	signal hysteresis can reduce the number of handler invocations
356	considerably, at the cost of two extra syscalls.	451	considerably, at the cost of two extra syscalls.
357		452
358	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
359	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
360	signals to be ignored by default.	455	signals to be ignored by default.
361		456
362	=item $async->block	457	=item $async->block
363		458
364	=item $async->unblock	459	=item $async->unblock
…		…
417	=item $fileno = $async->pipe_fileno	512	=item $fileno = $async->pipe_fileno
418		513
419	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
420	currently attached to the object, it will dynamically create one.	515	currently attached to the object, it will dynamically create one.
421		516
422	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
423	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
424	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
425	C<select>able.	520	C<select>able.
426		521
427	=item $async->pipe_autodrain ($enable)	522	=item $async->pipe_autodrain ($enable)
…		…
432	draining.	527	draining.
433		528
434	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
435	objects.	530	objects.
436		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
437	=item $async->post_fork	537	=item $async->post_fork
438		538
439	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
440	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
441	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
…		…
458		558
459	=back	559	=back
460		560
461	=head1 THE Async::Interrupt::EventPipe CLASS	561	=head1 THE Async::Interrupt::EventPipe CLASS
462		562
463	Pipes are the predominent utility to make asynchronous signals	563	Pipes are the predominant utility to make asynchronous signals
464	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
465	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
466	an C<eventfd> instead.	566	an C<eventfd> instead.
467		567
468	This class creates selectable event pipes in a portable fashion: on	568	This class creates selectable event pipes in a portable fashion: on
…		…
498		598
499	=item $epipe->drain	599	=item $epipe->drain
500		600
501	Drain (empty) the pipe.	601	Drain (empty) the pipe.
502		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
503	=item $epipe->renew	620	=item $epipe->renew
504		621
505	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
506	it's file descriptor number, but the writing side might.	623	it's file descriptor number, but the writing side might.
507		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
508	=back	631	=back
509		632
510	=cut	633	=cut
511		634
512	1;	635	1;
513
514	=head1 EXAMPLE
515
516	There really should be a complete C/XS example. Bug me about it. Better
517	yet, create one.
518		636
519	=head1 IMPLEMENTATION DETAILS AND LIMITATIONS	637	=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
520		638
521	This module works by "hijacking" SIGKILL, which is guaranteed to always	639	This module works by "hijacking" SIGKILL, which is guaranteed to always
522	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.19 by root, Tue Jul 28 13:17:05 2009 UTC vs. Revision 1.33 by root, Fri Apr 11 04:24:47 2014 UTC

Diff Legend

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.19 by root, Tue Jul 28 13:17:05 2009 UTC vs.
Revision 1.33 by root, Fri Apr 11 04:24:47 2014 UTC