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

Comparing Async-Interrupt/Interrupt.pm (file contents):
Revision 1.16 by root, Fri Jul 17 21:02:18 2009 UTC vs.
Revision 1.21 by root, Thu Jul 30 03:59:47 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	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
93	=head1 THE Async::Interrupt CLASS	225	=head1 THE Async::Interrupt CLASS
94		226
95	=over 4	227	=over 4
96		228
97	=cut	229	=cut
…		…
100		232
101	use common::sense;	233	use common::sense;
102		234
103	BEGIN {	235	BEGIN {
104	# the next line forces initialisation of internal	236	# the next line forces initialisation of internal
105	# signal handling # variables	237	# signal handling variables, otherwise, PL_sig_pending
		238	# etc. will be null pointers.
106	$SIG{KILL} = sub { };	239	$SIG{KILL} = sub { };
107		240
108	our $VERSION = '0.6';	241	our $VERSION = '1.0';
109		242
110	require XSLoader;	243	require XSLoader;
111	XSLoader::load ("Async::Interrupt", $VERSION);	244	XSLoader::load ("Async::Interrupt", $VERSION);
112	}	245	}
113		246
…		…
136	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
137	Async::Interrupt.	270	Async::Interrupt.
138		271
139	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,
140	and C<$Async::Interrupt::DIED> will be called with C<$@> containing	273	and C<$Async::Interrupt::DIED> will be called with C<$@> containing
141	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
142	continue.	275	continue.
143		276
144	=item c_cb => [$c_func, $c_arg]	277	=item c_cb => [$c_func, $c_arg]
145		278
146	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
…		…
162	which case the requirements set out for C<cb> apply as well).	295	which case the requirements set out for C<cb> apply as well).
163		296
164	=item var => $scalar_ref	297	=item var => $scalar_ref
165		298
166	When specified, then the given argument must be a reference to a	299	When specified, then the given argument must be a reference to a
167	scalar. The scalar will be set to C<0> intiially. Signalling the interrupt	300	scalar. The scalar will be set to C<0> initially. Signalling the interrupt
168	object will set it to the passed value, handling the interrupt will reset	301	object will set it to the passed value, handling the interrupt will reset
169	it to C<0> again.	302	it to C<0> again.
170		303
171	Note that the only thing you are legally allowed to do is to is to check	304	Note that the only thing you are legally allowed to do is to is to check
172	the variable in a boolean or integer context (e.g. comparing it with a	305	the variable in a boolean or integer context (e.g. comparing it with a
…		…
179	given signal, that is, it will effectively call C<< ->signal (0) >> each time	312	given signal, that is, it will effectively call C<< ->signal (0) >> each time
180	the given signal is caught by the process.	313	the given signal is caught by the process.
181		314
182	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
183	defaults when the Async::Interrupt object gets destroyed.	316	defaults when the Async::Interrupt object gets destroyed.
		317
		318	=item signal_hysteresis => $boolean
		319
		320	Sets the initial signal hysteresis state, see the C<signal_hysteresis>
		321	method, below.
184		322
185	=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]
186		324
187	Specifies two file descriptors (or file handles) that should be signalled	325	Specifies two file descriptors (or file handles) that should be signalled
188	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
…		…
202		340
203	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
204	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
205	those.	343	those.
206		344
		345	=item pipe_autodrain => $boolean
		346
		347	Sets the initial autodrain state, see the C<pipe_autodrain> method, below.
		348
207	=back	349	=back
208		350
209	=cut	351	=cut
210		352
211	sub new {	353	sub new {
212	my ($class, %arg) = @_;	354	my ($class, %arg) = @_;
213		355
214	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
215	}	364	}
216		365
217	=item ($signal_func, $signal_arg) = $async->signal_func	366	=item ($signal_func, $signal_arg) = $async->signal_func
218		367
219	Returns the address of a function to call asynchronously. The function has	368	Returns the address of a function to call asynchronously. The function
220	the following prototype and needs to be passed the specified C<$c_arg>,	369	has the following prototype and needs to be passed the specified
221	which is a C<void *> cast to C<IV>:	370	C<$signal_arg>, which is a C<void *> cast to C<IV>:
222		371
223	void (signal_func) (void signal_arg, int value)	372	void (signal_func) (void signal_arg, int value)
224		373
225	An example call would look like:	374	An example call would look like:
226		375
…		…
264	; // do something	413	; // do something
265		414
266	=item $async->signal ($value=1)	415	=item $async->signal ($value=1)
267		416
268	This signals the given async object from Perl code. Semi-obviously, this	417	This signals the given async object from Perl code. Semi-obviously, this
269	will instantly trigger the callback invocation.	418	will instantly trigger the callback invocation (it does not, as the name
		419	might imply, do anything with POSIX signals).
270		420
271	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>
272	(1..127 is portable).	422	(1..127 is portable).
		423
		424	=item $async->signal_hysteresis ($enable)
		425
		426	Enables or disables signal hysteresis (default: disabled). If a POSIX
		427	signal is used as a signal source for the interrupt object, then enabling
		428	signal hysteresis causes Async::Interrupt to reset the signal action to
		429	C<SIG_IGN> in the signal handler and restore it just before handling the
		430	interruption.
		431
		432	When you expect a lot of signals (e.g. when using SIGIO), then enabling
		433	signal hysteresis can reduce the number of handler invocations
		434	considerably, at the cost of two extra syscalls.
		435
		436	Note that setting the signal to C<SIG_IGN> can have unintended side
		437	effects when you fork and exec other programs, as often they do nto expect
		438	signals to be ignored by default.
273		439
274	=item $async->block	440	=item $async->block
275		441
276	=item $async->unblock	442	=item $async->unblock
277		443
…		…
292	This call C<< $async->block >> and installs a handler that is called when	458	This call C<< $async->block >> and installs a handler that is called when
293	the current scope is exited (via an exception, by canceling the Coro	459	the current scope is exited (via an exception, by canceling the Coro
294	thread, by calling last/goto etc.).	460	thread, by calling last/goto etc.).
295		461
296	This is the recommended (and fastest) way to implement critical sections.	462	This is the recommended (and fastest) way to implement critical sections.
		463
		464	=item ($block_func, $block_arg) = $async->scope_block_func
		465
		466	Returns the address of a function that implements the C<scope_block>
		467	functionality.
		468
		469	It has the following prototype and needs to be passed the specified
		470	C<$block_arg>, which is a C<void *> cast to C<IV>:
		471
		472	void (block_func) (void block_arg)
		473
		474	An example call would look like:
		475
		476	block_func (block_arg);
		477
		478	The function is safe to call only from within the toplevel of a perl XS
		479	function and will call C<LEAVE> and C<ENTER> (in this order!).
297		480
298	=item $async->pipe_enable	481	=item $async->pipe_enable
299		482
300	=item $async->pipe_disable	483	=item $async->pipe_disable
301		484
…		…
339	This only works when the pipe was created by Async::Interrupt.	522	This only works when the pipe was created by Async::Interrupt.
340		523
341	Async::Interrupt ensures that the reading file descriptor does not change	524	Async::Interrupt ensures that the reading file descriptor does not change
342	it's value.	525	it's value.
343		526
		527	=item $signum = Async::Interrupt::sig2num $signame_or_number
		528
		529	=item $signame = Async::Interrupt::sig2name $signame_or_number
		530
		531	These two convenience functions simply convert a signal name or number to
		532	the corresponding name or number. They are not used by this module and
		533	exist just because perl doesn't have a nice way to do this on its own.
		534
		535	They will return C<undef> on illegal names or numbers.
		536
344	=back	537	=back
345		538
346	=head1 THE Async::Interrupt::EventPipe CLASS	539	=head1 THE Async::Interrupt::EventPipe CLASS
347		540
348	Pipes are the predominent utility to make asynchronous signals	541	Pipes are the predominent utility to make asynchronous signals
…		…
383		576
384	=item $epipe->drain	577	=item $epipe->drain
385		578
386	Drain (empty) the pipe.	579	Drain (empty) the pipe.
387		580
		581	=item ($c_func, $c_arg) = $epipe->drain_func
		582
		583	Returns a function pointer and C<void *> argument that can be called to
		584	have the effect of C<< $epipe->drain >> on the XS level.
		585
		586	It has the following prototype and needs to be passed the specified
		587	C<$c_arg>, which is a C<void *> cast to C<IV>:
		588
		589	void (c_func) (void c_arg)
		590
		591	An example call would look like:
		592
		593	c_func (c_arg);
		594
388	=item $epipe->renew	595	=item $epipe->renew
389		596
390	Recreates the pipe (useful after a fork). The reading side will not change	597	Recreates the pipe (useful after a fork). The reading side will not change
391	it's file descriptor number, but the writing side might.	598	it's file descriptor number, but the writing side might.
392		599
		600	=item $epipe->wait
		601
		602	This method blocks the process until there are events on the pipe. This is
		603	not a very event-based or ncie way of usign an event pipe, but it can be
		604	occasionally useful.
		605
393	=back	606	=back
394		607
395	=cut	608	=cut
396		609
397	1;	610	1;
398
399	=head1 EXAMPLE
400
401	There really should be a complete C/XS example. Bug me about it. Better
402	yet, create one.
403		611
404	=head1 IMPLEMENTATION DETAILS AND LIMITATIONS	612	=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
405		613
406	This module works by "hijacking" SIGKILL, which is guaranteed to always	614	This module works by "hijacking" SIGKILL, which is guaranteed to always
407	exist, but also cannot be caught, so is always available.	615	exist, but also cannot be caught, so is always available.

Diff Legend

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

Comparing Async-Interrupt/Interrupt.pm (file contents): Revision 1.16 by root, Fri Jul 17 21:02:18 2009 UTC vs. Revision 1.21 by root, Thu Jul 30 03:59:47 2009 UTC

Diff Legend

Comparing Async-Interrupt/Interrupt.pm (file contents):
Revision 1.16 by root, Fri Jul 17 21:02:18 2009 UTC vs.
Revision 1.21 by root, Thu Jul 30 03:59:47 2009 UTC