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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.12 by root, Tue Jul 14 19:51:24 2009 UTC vs.
Revision 1.16 by root, Fri Jul 17 21:02:18 2009 UTC

…		…
88	I<running> interpreter, there is optional support for signalling a pipe	88	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	89	- 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>	90	L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
91	and C<write> syscall.	91	and C<write> syscall.
92		92
		93	=head1 THE Async::Interrupt CLASS
		94
93	=over 4	95	=over 4
94		96
95	=cut	97	=cut
96		98
97	package Async::Interrupt;	99	package Async::Interrupt;
…		…
101	BEGIN {	103	BEGIN {
102	# the next line forces initialisation of internal	104	# the next line forces initialisation of internal
103	# signal handling # variables	105	# signal handling # variables
104	$SIG{KILL} = sub { };	106	$SIG{KILL} = sub { };
105		107
106	our $VERSION = '0.042';	108	our $VERSION = '0.6';
107		109
108	require XSLoader;	110	require XSLoader;
109	XSLoader::load ("Async::Interrupt", $VERSION);	111	XSLoader::load ("Async::Interrupt", $VERSION);
110	}	112	}
111		113
…		…
157	might use (the exception is C<errno>, which is saved and restored by	159	might use (the exception is C<errno>, which is saved and restored by
158	Async::Interrupt). The callback itself runs as part of the perl context,	160	Async::Interrupt). The callback itself runs as part of the perl context,
159	so you can call any perl functions and modify any perl data structures (in	161	so you can call any perl functions and modify any perl data structures (in
160	which case the requirements set out for C<cb> apply as well).	162	which case the requirements set out for C<cb> apply as well).
161		163
		164	=item var => $scalar_ref
		165
		166	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
		168	object will set it to the passed value, handling the interrupt will reset
		169	it to C<0> again.
		170
		171	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
		173	string, or printing it, will I<destroy> it and might cause your program to
		174	crash or worse).
		175
162	=item signal => $signame_or_value	176	=item signal => $signame_or_value
163		177
164	When this parameter is specified, then the Async::Interrupt will hook the	178	When this parameter is specified, then the Async::Interrupt will hook the
165	given signal, that is, it will effectively call C<< ->signal (0) >> each time	179	given signal, that is, it will effectively call C<< ->signal (0) >> each time
166	the given signal is caught by the process.	180	the given signal is caught by the process.
…		…
175	be written to it, and before the callback is being invoked, it will be	189	be written to it, and before the callback is being invoked, it will be
176	read again. Due to races, it is unlikely but possible that multiple octets	190	read again. Due to races, it is unlikely but possible that multiple octets
177	are written. It is required that the file handles are both in nonblocking	191	are written. It is required that the file handles are both in nonblocking
178	mode.	192	mode.
179		193
180	You can get a portable pipe and set non-blocking mode portably by using
181	e.g. L<AnyEvent::Util> from the L<AnyEvent> distribution.
182
183	It is also possible to pass in a linux eventfd as both read and write
184	handle (which is faster than a pipe).
185
186	The object will keep a reference to the file handles.	194	The object will keep a reference to the file handles.
187		195
188	This can be used to ensure that async notifications will interrupt event	196	This can be used to ensure that async notifications will interrupt event
189	frameworks as well.	197	frameworks as well.
190		198
		199	Note that C<Async::Interrupt> will create a suitable signal fd
		200	automatically when your program requests one, so you don't have to specify
		201	this argument when all you want is an extra file descriptor to watch.
		202
		203	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
		205	those.
		206
191	=back	207	=back
192		208
193	=cut	209	=cut
194		210
195	sub new {	211	sub new {
196	my ($class, %arg) = @_;	212	my ($class, %arg) = @_;
197		213
198	bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}), $class	214	bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class
199	}	215	}
200		216
201	=item ($signal_func, $signal_arg) = $async->signal_func	217	=item ($signal_func, $signal_arg) = $async->signal_func
202		218
203	Returns the address of a function to call asynchronously. The function has	219	Returns the address of a function to call asynchronously. The function has
…		…
211	signal_func (signal_arg, 0);	227	signal_func (signal_arg, 0);
212		228
213	The function is safe to call from within signal and thread contexts, at	229	The function is safe to call from within signal and thread contexts, at
214	any time. The specified C<value> is passed to both C and Perl callback.	230	any time. The specified C<value> is passed to both C and Perl callback.
215		231
216	C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is	232	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
217	portable).	233	(1..127 is portable).
218		234
219	If the function is called while the Async::Interrupt object is already	235	If the function is called while the Async::Interrupt object is already
220	signaled but before the callbacks are being executed, then the stored	236	signaled but before the callbacks are being executed, then the stored
221	C<value> is either the old or the new one. Due to the asynchronous	237	C<value> is either the old or the new one. Due to the asynchronous
222	nature of the code, the C<value> can even be passed to two consecutive	238	nature of the code, the C<value> can even be passed to two consecutive
223	invocations of the callback.	239	invocations of the callback.
224		240
		241	=item $address = $async->c_var
		242
		243	Returns the address (cast to IV) of an C<IV> variable. The variable is set
		244	to C<0> initially and gets set to the passed value whenever the object
		245	gets signalled, and reset to C<0> once the interrupt has been handled.
		246
		247	Note that it is often beneficial to just call C<PERL_ASYNC_CHECK ()> to
		248	handle any interrupts.
		249
		250	Example: call some XS function to store the address, then show C code
		251	waiting for it.
		252
		253	my_xs_func $async->c_var;
		254
		255	static IV *valuep;
		256
		257	void
		258	my_xs_func (void *addr)
		259	CODE:
		260	valuep = (IV *)addr;
		261
		262	// code in a loop, waiting
		263	while (!*valuep)
		264	; // do something
		265
225	=item $async->signal ($value=0)	266	=item $async->signal ($value=1)
226		267
227	This signals the given async object from Perl code. Semi-obviously, this	268	This signals the given async object from Perl code. Semi-obviously, this
228	will instantly trigger the callback invocation.	269	will instantly trigger the callback invocation.
229		270
230	C<$value> must be in the valid range for a C<sig_atomic_t> (0..127 is	271	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
231	portable).	272	(1..127 is portable).
232		273
233	=item $async->block	274	=item $async->block
234		275
235	=item $async->unblock	276	=item $async->unblock
236		277
…		…
262	enabled). Writing to a pipe is relatively expensive, so it can be disabled	303	enabled). Writing to a pipe is relatively expensive, so it can be disabled
263	when you know you are not waiting for it (for example, with L<EV> you	304	when you know you are not waiting for it (for example, with L<EV> you
264	could disable the pipe in a check watcher, and enable it in a prepare	305	could disable the pipe in a check watcher, and enable it in a prepare
265	watcher).	306	watcher).
266		307
267	Note that when C<fd_disable> is in effect, no attempt to read from the	308	Note that currently, while C<pipe_disable> is in effect, no attempt to
268	pipe will be done.	309	read from the pipe will be done when handling events. This might change as
		310	soon as I realize why this is a mistake.
		311
		312	=item $fileno = $async->pipe_fileno
		313
		314	Returns the reading side of the signalling pipe. If no signalling pipe is
		315	currently attached to the object, it will dynamically create one.
		316
		317	Note that the only valid oepration on this file descriptor is to wait
		318	until it is readable. The fd might belong currently to a pipe, a tcp
		319	socket, or an eventfd, depending on the platform, and is guaranteed to be
		320	C<select>able.
		321
		322	=item $async->pipe_autodrain ($enable)
		323
		324	Enables (C<1>) or disables (C<0>) automatic draining of the pipe (default:
		325	enabled). When automatic draining is enabled, then Async::Interrupt will
		326	automatically clear the pipe. Otherwise the user is responsible for this
		327	draining.
		328
		329	This is useful when you want to share one pipe among many Async::Interrupt
		330	objects.
		331
		332	=item $async->post_fork
		333
		334	The object will not normally be usable after a fork (as the pipe fd is
		335	shared between processes). Calling this method after a fork in the child
		336	ensures that the object will work as expected again. It only needs to be
		337	called when the async object is used in the child.
		338
		339	This only works when the pipe was created by Async::Interrupt.
		340
		341	Async::Interrupt ensures that the reading file descriptor does not change
		342	it's value.
		343
		344	=back
		345
		346	=head1 THE Async::Interrupt::EventPipe CLASS
		347
		348	Pipes are the predominent utility to make asynchronous signals
		349	synchronous. However, pipes are hard to come by: they don't exist on the
		350	broken windows platform, and on GNU/Linux systems, you might want to use
		351	an C<eventfd> instead.
		352
		353	This class creates selectable event pipes in a portable fashion: on
		354	windows, it will try to create a tcp socket pair, on GNU/Linux, it will
		355	try to create an eventfd and everywhere else it will try to use a normal
		356	pipe.
		357
		358	=over 4
		359
		360	=item $epipe = new Async::Interrupt::EventPipe
		361
		362	This creates and returns an eventpipe object. This object is simply a
		363	blessed array reference:
		364
		365	=item ($r_fd, $w_fd) = $epipe->filenos
		366
		367	Returns the read-side file descriptor and the write-side file descriptor.
		368
		369	Example: pass an eventpipe object as pipe to the Async::Interrupt
		370	constructor, and create an AnyEvent watcher for the read side.
		371
		372	my $epipe = new Async::Interrupt::EventPipe;
		373	my $asy = new Async::Interrupt pipe => [$epipe->filenos];
		374	my $iow = AnyEvent->io (fh => $epipe->fileno, poll => 'r', cb => sub { });
		375
		376	=item $r_fd = $epipe->fileno
		377
		378	Return only the reading/listening side.
		379
		380	=item $epipe->signal
		381
		382	Write something to the pipe, in a portable fashion.
		383
		384	=item $epipe->drain
		385
		386	Drain (empty) the pipe.
		387
		388	=item $epipe->renew
		389
		390	Recreates the pipe (useful after a fork). The reading side will not change
		391	it's file descriptor number, but the writing side might.
		392
		393	=back
269		394
270	=cut	395	=cut
271		396
272	1;	397	1;
273
274	=back
275		398
276	=head1 EXAMPLE	399	=head1 EXAMPLE
277		400
278	There really should be a complete C/XS example. Bug me about it. Better	401	There really should be a complete C/XS example. Bug me about it. Better
279	yet, create one.	402	yet, create one.
…		…
287	then intercepts the interpreter handling it. This makes normal signal	410	then intercepts the interpreter handling it. This makes normal signal
288	handling slower (probably unmeasurably, though), but has the advantage	411	handling slower (probably unmeasurably, though), but has the advantage
289	of not requiring a special runops function, nor slowing down normal perl	412	of not requiring a special runops function, nor slowing down normal perl
290	execution a bit.	413	execution a bit.
291		414
292	It assumes that C<sig_atomic_t> and C<int> are both async-safe to modify	415	It assumes that C<sig_atomic_t>, C<int> and C<IV> are all async-safe to
293	(C<sig_atomic_> is used by this module, and perl itself uses C<int>, so we	416	modify.
294	can assume that this is quite portable, at least w.r.t. signals).
295		417
296	=head1 AUTHOR	418	=head1 AUTHOR
297		419
298	Marc Lehmann <schmorp@schmorp.de>	420	Marc Lehmann <schmorp@schmorp.de>
299	http://home.schmorp.de/	421	http://home.schmorp.de/

Diff Legend

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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents): Revision 1.12 by root, Tue Jul 14 19:51:24 2009 UTC vs. Revision 1.16 by root, Fri Jul 17 21:02:18 2009 UTC

Diff Legend

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.12 by root, Tue Jul 14 19:51:24 2009 UTC vs.
Revision 1.16 by root, Fri Jul 17 21:02:18 2009 UTC