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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents):
Revision 1.1 by root, Thu Jul 2 13:41:44 2009 UTC vs.
Revision 1.33 by root, Fri Apr 11 04:24:47 2014 UTC

…		…
7	use Async::Interrupt;	7	use Async::Interrupt;
8		8
9	=head1 DESCRIPTION	9	=head1 DESCRIPTION
10		10
11	This module implements a single feature only of interest to advanced perl	11	This module implements a single feature only of interest to advanced perl
12	modules, namely asynchronous interruptions (think "unix signals", which	12	modules, namely asynchronous interruptions (think "UNIX signals", which
13	are very similar).	13	are very similar).
14		14
15	Sometimes, modules wish to run code asynchronously (in another thread),	15	Sometimes, modules wish to run code asynchronously (in another thread,
16	and then signal the perl interpreter on certain events. One common way is	16	or from a signal handler), and then signal the perl interpreter on
17	to write some data to a pipe and use an event handling toolkit to watch	17	certain events. One common way is to write some data to a pipe and use an
18	for I/O events. Another way is to send a signal. Those methods are slow,	18	event handling toolkit to watch for I/O events. Another way is to send
19	and in the case of a pipe, also not asynchronous - it won't interrupt a	19	a signal. Those methods are slow, and in the case of a pipe, also not
20	running perl interpreter.	20	asynchronous - it won't interrupt a running perl interpreter.
21		21
22	This module implements asynchronous notifications that enable you to	22	This module implements asynchronous notifications that enable you to
23	signal running perl code form another thread, asynchronously, without	23	signal running perl code from another thread, asynchronously, and
24	issuing syscalls.	24	sometimes even without using a single syscall.
		25
		26	=head2 USAGE SCENARIOS
25		27
26	=over 4	28	=over 4
27		29
		30	=item Race-free signal handling
		31
		32	There seems to be no way to do race-free signal handling in perl: to
		33	catch a signal, you have to execute Perl code, and between entering the
		34	interpreter C<select> function (or other blocking functions) and executing
		35	the select syscall is a small but relevant timespan during which signals
		36	will be queued, but perl signal handlers will not be executed and the
		37	blocking syscall will not be interrupted.
		38
		39	You can use this module to bind a signal to a callback while at the same
		40	time activating an event pipe that you can C<select> on, fixing the race
		41	completely.
		42
		43	This can be used to implement the signal hadling in event loops,
		44	e.g. L<AnyEvent>, L<POE>, L<IO::Async::Loop> and so on.
		45
		46	=item Background threads want speedy reporting
		47
		48	Assume you want very exact timing, and you can spare an extra cpu core
		49	for that. Then you can run an extra thread that signals your perl
		50	interpreter. This means you can get a very exact timing source while your
		51	perl code is number crunching, without even using a syscall to communicate
		52	between your threads.
		53
		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
		56	clients.
		57
		58	Or L<EV::Loop::Async> uses an interrupt object to wake up perl when new
		59	events have arrived.
		60
		61	L<IO::AIO> and L<BDB> could also use this to speed up result reporting.
		62
		63	=item Speedy event loop invocation
		64
		65	One could use this module e.g. in L<Coro> to interrupt a running coro-thread
		66	and cause it to enter the event loop.
		67
		68	Or one could bind to C<SIGIO> and tell some important sockets to send this
		69	signal, causing the event loop to be entered to reduce network latency.
		70
		71	=back
		72
		73	=head2 HOW TO USE
		74
		75	You can use this module by creating an C<Async::Interrupt> object for each
		76	such event source. This object stores a perl and/or a C-level callback
		77	that is invoked when the C<Async::Interrupt> object gets signalled. It is
		78	executed at the next time the perl interpreter is running (i.e. it will
		79	interrupt a computation, but not an XS function or a syscall).
		80
		81	You can signal the C<Async::Interrupt> object either by calling it's C<<
		82	->signal >> method, or, more commonly, by calling a C function. There is
		83	also the built-in (POSIX) signal source.
		84
		85	The C<< ->signal_func >> returns the address of the C function that is to
		86	be called (plus an argument to be used during the call). The signalling
		87	function also takes an integer argument in the range SIG_ATOMIC_MIN to
		88	SIG_ATOMIC_MAX (guaranteed to allow at least 0..127).
		89
		90	Since this kind of interruption is fast, but can only interrupt a
		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
		93	L<EV> or L<AnyEvent>). This, of course, incurs the overhead of a C<read>
		94	and C<write> syscall.
		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
		225	=head1 THE Async::Interrupt CLASS
		226
		227	=over 4
		228
28	=cut	229	=cut
29		230
30	package Async::Interrupt;	231	package Async::Interrupt;
31		232
		233	use common::sense;
		234
32	BEGIN {	235	BEGIN {
		236	# the next line forces initialisation of internal
		237	# signal handling variables, otherwise, PL_sig_pending
		238	# etc. might be null pointers.
		239	$SIG{KILL} = sub { };
		240
33	$VERSION = '0.02';	241	our $VERSION = '1.2';
34		242
35	require XSLoader;	243	require XSLoader;
36	XSLoader::load Async::Interrupt::, $VERSION;	244	XSLoader::load ("Async::Interrupt", $VERSION);
37	}	245	}
		246
		247	our $DIED = sub { warn "$@" };
38		248
39	=item $async = new Async::Interrupt key => value...	249	=item $async = new Async::Interrupt key => value...
40		250
41	Creates a new Async::Interrupt object. You may only use async	251	Creates a new Async::Interrupt object. You may only use async
42	notifications on this object while it exists, so you need to keep a	252	notifications on this object while it exists, so you need to keep a
…		…
51		261
52	Registers a perl callback to be invoked whenever the async interrupt is	262	Registers a perl callback to be invoked whenever the async interrupt is
53	signalled.	263	signalled.
54		264
55	Note that, since this callback can be invoked at basically any time, it	265	Note that, since this callback can be invoked at basically any time, it
56	must not modify any well-known global variables such as C<$/>, C<$@> or	266	must not modify any well-known global variables such as C<$/> without
57	C<$!>, without restoring them again before returning.	267	restoring them again before returning.
58		268
		269	The exceptions are C<$!> and C<$@>, which are saved and restored by
		270	Async::Interrupt.
		271
		272	If the callback should throw an exception, then it will be caught,
		273	and C<$Async::Interrupt::DIED> will be called with C<$@> containing
		274	the exception. The default will simply C<warn> about the message and
		275	continue.
		276
59	=item c_cb => [$c_func, $c_data]	277	=item c_cb => [$c_func, $c_arg]
60		278
61	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
62	signalled.	280	signalled.
63		281
64	The C callback must have the following prototype:	282	The C callback must have the following prototype:
65		283
66	void c_func (pTHX_ void *c_data, int value);	284	void c_func (pTHX_ void *c_arg, int value);
67		285
68	Both C<$c_func> and C<$c_data> must be specified as integers/IVs.	286	Both C<$c_func> and C<$c_arg> must be specified as integers/IVs, and
		287	C<$value> is the C<value> passed to some earlier call to either C<$signal>
		288	or the C<signal_func> function.
69		289
70	Note that, because the callback can be invoked at almost any time, you	290	Note that, because the callback can be invoked at almost any time, you
71	have to be careful at saving and restoring global variables that Perl	291	have to be careful at saving and restoring global variables that Perl
72	might use, most notably C<errno>. The callback itself runs as part of the	292	might use (the exception is C<errno>, which is saved and restored by
73	perl context, so you can call any perl functions and modify any perl data	293	Async::Interrupt). The callback itself runs as part of the perl context,
74	structures.	294	so you can call any perl functions and modify any perl data structures (in
		295	which case the requirements set out for C<cb> apply as well).
75		296
76	=item fh => $fileno_or_fh	297	=item var => $scalar_ref
77		298
		299	When specified, then the given argument must be a reference to a
		300	scalar. The scalar will be set to C<0> initially. Signalling the interrupt
		301	object will set it to the passed value, handling the interrupt will reset
		302	it to C<0> again.
		303
		304	Note that the only thing you are legally allowed to do is to is to check
		305	the variable in a boolean or integer context (e.g. comparing it with a
		306	string, or printing it, will I<destroy> it and might cause your program to
		307	crash or worse).
		308
		309	=item signal => $signame_or_value
		310
		311	When this parameter is specified, then the Async::Interrupt will hook the
		312	given signal, that is, it will effectively call C<< ->signal (0) >> each time
		313	the given signal is caught by the process.
		314
		315	Only one async can hook a given signal, and the signal will be restored to
		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.
		322
		323	=item pipe => [$fileno_or_fh_for_reading, $fileno_or_fh_for_writing]
		324
78	Specifies a file descriptor (or file handle) that should be signalled	325	Specifies two file descriptors (or file handles) that should be signalled
79	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
80	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
81	read again. Due to races, it is unlikely but possible that multiple octets	328	read again. Due to races, it is unlikely but possible that multiple octets
82	are written, therefore, it is recommended that the file handle is in	329	are written. It is required that the file handles are both in nonblocking
83	nonblocking mode.	330	mode.
84		331
85	(You can get a portable pipe and set non-blocking mode portably by using
86	e.g. L<AnyEvent::Util> from the L<AnyEvent> distro).
87
88	The object will keep a reference to the file handle.	332	The object will keep a reference to the file handles.
89		333
90	This can be used to ensure that async notifications will interrupt event	334	This can be used to ensure that async notifications will interrupt event
91	frameworks as well.	335	frameworks as well.
92		336
		337	Note that C<Async::Interrupt> will create a suitable signal fd
		338	automatically when your program requests one, so you don't have to specify
		339	this argument when all you want is an extra file descriptor to watch.
		340
		341	If you want to share a single event pipe between multiple Async::Interrupt
		342	objects, you can use the C<Async::Interrupt::EventPipe> class to manage
		343	those.
		344
		345	=item pipe_autodrain => $boolean
		346
		347	Sets the initial autodrain state, see the C<pipe_autodrain> method, below.
		348
93	=back	349	=back
94		350
95	=cut	351	=cut
96		352
97	sub new {	353	sub new {
98	my ($class, %arg) = @_;	354	my ($class, %arg) = @_;
99		355
100	my $self = _alloc $arg{cb}, @{$arg{c_cb}}[0,1], $arg{fh};	356	my $self = bless \(_alloc $arg{cb}, @{$arg{c_cb}}[0,1], @{$arg{pipe}}[0,1], $arg{signal}, $arg{var}), $class;
101	bless \$self, $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
102	}	364	}
103		365
104	=item ($signal_func, $signal_arg) = $async->signal_cb	366	=item ($signal_func, $signal_arg) = $async->signal_func
105		367
106	Returns the address of a function to call asynchronously. The function has	368	Returns the address of a function to call asynchronously. The function
107	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
108	which is a C<void *> cast to C<IV>:	370	C<$signal_arg>, which is a C<void *> cast to C<IV>:
109		371
110	void (signal_func) (void signal_arg, int value)	372	void (signal_func) (void signal_arg, int value)
111		373
112	An example call would look like:	374	An example call would look like:
113		375
114	signal_func (signal_arg, 0);	376	signal_func (signal_arg, 0);
115		377
116	The function is safe toc all from within signal and thread contexts, at	378	The function is safe to call from within signal and thread contexts, at
117	any time. The specified C<value> is passed to both C and Perl callback.	379	any time. The specified C<value> is passed to both C and Perl callback.
		380
		381	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
		382	(1..127 is portable).
118		383
119	If the function is called while the Async::Interrupt object is already	384	If the function is called while the Async::Interrupt object is already
120	signaled but before the callbacks are being executed, then the stored	385	signaled but before the callbacks are being executed, then the stored
121	C<value> is being overwritten. Due to the asynchronous nature of the code,	386	C<value> is either the old or the new one. Due to the asynchronous
122	the C<value> can even be passed to two consecutive invocations of the	387	nature of the code, the C<value> can even be passed to two consecutive
123	callback.	388	invocations of the callback.
124		389
		390	=item $address = $async->c_var
		391
		392	Returns the address (cast to IV) of an C<IV> variable. The variable is set
		393	to C<0> initially and gets set to the passed value whenever the object
		394	gets signalled, and reset to C<0> once the interrupt has been handled.
		395
		396	Note that it is often beneficial to just call C<PERL_ASYNC_CHECK ()> to
		397	handle any interrupts.
		398
		399	Example: call some XS function to store the address, then show C code
		400	waiting for it.
		401
		402	my_xs_func $async->c_var;
		403
		404	static IV *valuep;
		405
		406	void
		407	my_xs_func (void *addr)
		408	CODE:
		409	valuep = (IV *)addr;
		410
		411	// code in a loop, waiting
		412	while (!*valuep)
		413	; // do something
		414
125	=item $async->signal ($value=0)	415	=item $async->signal ($value=1)
126		416
127	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
128	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).
		420
		421	C<$value> must be in the valid range for a C<sig_atomic_t>, except C<0>
		422	(1..127 is portable).
		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
		441	=item $async->signal_hysteresis ($enable)
		442
		443	Enables or disables signal hysteresis (default: disabled). If a POSIX
		444	signal is used as a signal source for the interrupt object, then enabling
		445	signal hysteresis causes Async::Interrupt to reset the signal action to
		446	C<SIG_IGN> in the signal handler and restore it just before handling the
		447	interruption.
		448
		449	When you expect a lot of signals (e.g. when using SIGIO), then enabling
		450	signal hysteresis can reduce the number of handler invocations
		451	considerably, at the cost of two extra syscalls.
		452
		453	Note that setting the signal to C<SIG_IGN> can have unintended side
		454	effects when you fork and exec other programs, as often they do not expect
		455	signals to be ignored by default.
		456
		457	=item $async->block
		458
		459	=item $async->unblock
		460
		461	Sometimes you need a "critical section" of code that will not be
		462	interrupted by an Async::Interrupt. This can be implemented by calling C<<
		463	$async->block >> before the critical section, and C<< $async->unblock >>
		464	afterwards.
		465
		466	Note that there must be exactly one call of C<unblock> for every previous
		467	call to C<block> (i.e. calls can nest).
		468
		469	Since ensuring this in the presence of exceptions and threads is
		470	usually more difficult than you imagine, I recommend using C<<
		471	$async->scoped_block >> instead.
		472
		473	=item $async->scope_block
		474
		475	This call C<< $async->block >> and installs a handler that is called when
		476	the current scope is exited (via an exception, by canceling the Coro
		477	thread, by calling last/goto etc.).
		478
		479	This is the recommended (and fastest) way to implement critical sections.
		480
		481	=item ($block_func, $block_arg) = $async->scope_block_func
		482
		483	Returns the address of a function that implements the C<scope_block>
		484	functionality.
		485
		486	It has the following prototype and needs to be passed the specified
		487	C<$block_arg>, which is a C<void *> cast to C<IV>:
		488
		489	void (block_func) (void block_arg)
		490
		491	An example call would look like:
		492
		493	block_func (block_arg);
		494
		495	The function is safe to call only from within the toplevel of a perl XS
		496	function and will call C<LEAVE> and C<ENTER> (in this order!).
		497
		498	=item $async->pipe_enable
		499
		500	=item $async->pipe_disable
		501
		502	Enable/disable signalling the pipe when the interrupt occurs (default is
		503	enabled). Writing to a pipe is relatively expensive, so it can be disabled
		504	when you know you are not waiting for it (for example, with L<EV> you
		505	could disable the pipe in a check watcher, and enable it in a prepare
		506	watcher).
		507
		508	Note that currently, while C<pipe_disable> is in effect, no attempt to
		509	read from the pipe will be done when handling events. This might change as
		510	soon as I realize why this is a mistake.
		511
		512	=item $fileno = $async->pipe_fileno
		513
		514	Returns the reading side of the signalling pipe. If no signalling pipe is
		515	currently attached to the object, it will dynamically create one.
		516
		517	Note that the only valid operation on this file descriptor is to wait
		518	until it is readable. The fd might belong currently to a pipe, a tcp
		519	socket, or an eventfd, depending on the platform, and is guaranteed to be
		520	C<select>able.
		521
		522	=item $async->pipe_autodrain ($enable)
		523
		524	Enables (C<1>) or disables (C<0>) automatic draining of the pipe (default:
		525	enabled). When automatic draining is enabled, then Async::Interrupt will
		526	automatically clear the pipe. Otherwise the user is responsible for this
		527	draining.
		528
		529	This is useful when you want to share one pipe among many Async::Interrupt
		530	objects.
		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
		537	=item $async->post_fork
		538
		539	The object will not normally be usable after a fork (as the pipe fd is
		540	shared between processes). Calling this method after a fork in the child
		541	ensures that the object will work as expected again. It only needs to be
		542	called when the async object is used in the child.
		543
		544	This only works when the pipe was created by Async::Interrupt.
		545
		546	Async::Interrupt ensures that the reading file descriptor does not change
		547	it's value.
		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
		559	=back
		560
		561	=head1 THE Async::Interrupt::EventPipe CLASS
		562
		563	Pipes are the predominant utility to make asynchronous signals
		564	synchronous. However, pipes are hard to come by: they don't exist on the
		565	broken windows platform, and on GNU/Linux systems, you might want to use
		566	an C<eventfd> instead.
		567
		568	This class creates selectable event pipes in a portable fashion: on
		569	windows, it will try to create a tcp socket pair, on GNU/Linux, it will
		570	try to create an eventfd and everywhere else it will try to use a normal
		571	pipe.
		572
		573	=over 4
		574
		575	=item $epipe = new Async::Interrupt::EventPipe
		576
		577	This creates and returns an eventpipe object. This object is simply a
		578	blessed array reference:
		579
		580	=item ($r_fd, $w_fd) = $epipe->filenos
		581
		582	Returns the read-side file descriptor and the write-side file descriptor.
		583
		584	Example: pass an eventpipe object as pipe to the Async::Interrupt
		585	constructor, and create an AnyEvent watcher for the read side.
		586
		587	my $epipe = new Async::Interrupt::EventPipe;
		588	my $asy = new Async::Interrupt pipe => [$epipe->filenos];
		589	my $iow = AnyEvent->io (fh => $epipe->fileno, poll => 'r', cb => sub { });
		590
		591	=item $r_fd = $epipe->fileno
		592
		593	Return only the reading/listening side.
		594
		595	=item $epipe->signal
		596
		597	Write something to the pipe, in a portable fashion.
		598
		599	=item $epipe->drain
		600
		601	Drain (empty) the pipe.
		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
		620	=item $epipe->renew
		621
		622	Recreates the pipe (useful after a fork). The reading side will not change
		623	it's file descriptor number, but the writing side might.
		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
		631	=back
129		632
130	=cut	633	=cut
131		634
132	1;	635	1;
133		636
134	=back	637	=head1 IMPLEMENTATION DETAILS AND LIMITATIONS
		638
		639	This module works by "hijacking" SIGKILL, which is guaranteed to always
		640	exist, but also cannot be caught, so is always available.
		641
		642	Basically, this module fakes the occurance of a SIGKILL signal and
		643	then intercepts the interpreter handling it. This makes normal signal
		644	handling slower (probably unmeasurably, though), but has the advantage
		645	of not requiring a special runops function, nor slowing down normal perl
		646	execution a bit.
		647
		648	It assumes that C<sig_atomic_t>, C<int> and C<IV> are all async-safe to
		649	modify.
135		650
136	=head1 AUTHOR	651	=head1 AUTHOR
137		652
138	Marc Lehmann <schmorp@schmorp.de>	653	Marc Lehmann <schmorp@schmorp.de>
139	http://home.schmorp.de/	654	http://home.schmorp.de/

Diff Legend

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

Comparing cvsroot/Async-Interrupt/Interrupt.pm (file contents): Revision 1.1 by root, Thu Jul 2 13:41:44 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.1 by root, Thu Jul 2 13:41:44 2009 UTC vs.
Revision 1.33 by root, Fri Apr 11 04:24:47 2014 UTC