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

Comparing EV-Loop-Async/Async.pm (file contents):
Revision 1.1 by root, Tue Jul 14 02:59:55 2009 UTC vs.
Revision 1.5 by root, Fri Jul 17 15:06:25 2009 UTC

…		…
2		2
3	EV::Loop::Async - run an EV event loop asynchronously	3	EV::Loop::Async - run an EV event loop asynchronously
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
7	use EV::Loop::Async;	7	use EV::Loop::Async;
		8
		9	my $loop = EV::Loop::Async::default;
		10	my $timer;
		11	my $flag;
		12
		13	# create a watcher, but make sure the loop is locked
		14	{
		15	$loop->scope_lock; # lock the loop structures
		16	$timer = $loop->timer (5, 1, sub { $flag = 1 });
		17	$loop->notify; # tell loop to take note of the timer
		18	}
		19
		20	1 while $flag; # $flag will be set asynchronously
		21
		22	# implement a critical section, uninterrupted by any callbacks
		23	{
		24	$loop->interrupt->scope_block;
		25	# critical section, no watcher callback interruptions
		26	}
		27
		28	# stop the timer watcher again - locking is required once more
		29	{
		30	$loop->scope_lock; # lock the loop structures
		31	$timer->stop;
		32	# no need to notify
		33	}
8		34
9	=head1 DESCRIPTION	35	=head1 DESCRIPTION
10		36
11	TODO.	37	This module implements a rather specialised event loop - it takes a normal
		38	L<EV> event loop and runs it in a separate thread. That means it will poll
		39	for events even while your foreground Perl interpreter is busy (you don't
		40	need to have perls pseudo-threads enabled for this either).
		41
		42	Whenever the event loop detecs new events, it will interrupt perl and ask
		43	it to invoke all the pending watcher callbacks. This invocation will be
		44	"synchronous" (in the perl thread), but it can happen at any time.
		45
		46	See the documentation for L<Async::Interrupt> for details on when and how
		47	your perl program can be interrupted (and how to avoid it), and how to
		48	integrate background event loops into foreground ones.
		49
		50	=head1 FAQ
		51
		52	=over 4
		53
		54	=item Why on earth...???
		55
		56	Sometimes you need lower latency for specific events, but it's too heavy
		57	to continuously poll for events. And perl already does this for you
		58	anyways, so this module only uses this existing mechanism.
		59
		60	=item When do I have to lock?
		61
		62	When in doubt, lock. Do not start or stop a watcher, do not create a
		63	watcher (unless with the C<_ns> methods) and do not DESTROY an active
		64	watcher without locking either.
		65
		66	Any other event loop modifications need to be done while locked as
		67	well. So when in doubt, lock (best using C<scope_lock>).
		68
		69	=item Why explicit locking?
		70
		71	Because I was too lazy to wrap everything and there are probably only a
		72	few people on this world using this module.
		73
		74	=back
		75
		76	=head1 FUNCTIONS, METHODS AND VARIABLES OF THIS MODULE
12		77
13	=over 4	78	=over 4
14		79
15	=cut	80	=cut
16		81
…		…
34		99
35	Return the default loop, usable by all programs. The default loop will be	100	Return the default loop, usable by all programs. The default loop will be
36	created on the first call to C<default> by calling X<new EV::Loop>, and	101	created on the first call to C<default> by calling X<new EV::Loop>, and
37	should be used by all programs unless they have special requirements.	102	should be used by all programs unless they have special requirements.
38		103
39	=cut	104	The associated L<Async::Interrupt> object is stored in
		105	C<$EV::Loop::Async::AI>, and can be used to lock critical sections etc.
40		106
41	our ($LOOP, $ASYNC);	107	=cut
		108
		109	our ($LOOP, $INTERRUPT);
42		110
43	sub default() {	111	sub default() {
44	$LOOP \|\| do {	112	$LOOP \|\| do {
45	$LOOP = new EV::Loop::Async;	113	$LOOP = new EV::Loop::Async;
46	# $ASYNC = $LOOP->async;	114	$INTERRUPT = $LOOP->interrupt;
47		115
48	$LOOP	116	$LOOP
49	}	117	}
50	}	118	}
51		119
		120	=item $EV::Loop::Async::LOOP
52		121
		122	The default async loop, available after the first call to
		123	C<EV::Loop::Async::default>.
		124
		125	=item $EV::Loop::Async::INTERRUPT
		126
		127	The default loop's L<Async::Interrupt> object, for easy access.
		128
		129	Example: create a section of code where no callback invocations will
		130	interrupt:
		131
		132	{
		133	$EV::Loop::Async::INTERRUPT->scope_block;
		134	# no default loop callbacks will be executed here.
		135	# the loop will not be locked, however.
		136	}
		137
		138	Example: embed the default EV::Async::Loop loop into the default L<EV>
		139	loop (note that it could be any other event loop as well).
		140
		141	my $async_w = EV::io
		142	$EV::Loop::Async::LOOP->interrupt->pipe_fileno,
		143	EV::READ,
		144	sub { };
		145
53	=item $loop = new EV::Loop $flags, [Async-Interrupt-Arguments...]	146	=item $loop = new EV::Loop::Async $flags, [Async-Interrupt-Arguments...]
54		147
55	This constructor:	148	This constructor:
56		149
57	=over 4	150	=over 4
58		151
59	=item 1. creates a new C<EV::Loop> (similar C<new EV::Loop>).	152	=item 1. creates a new C<EV::Loop> (similar C<new EV::Loop>).
60		153
61	=item 2. creates a new L<Async::Interrupt> object and attaches itself to it.	154	=item 2. creates a new L<Async::Interrupt> object and attaches itself to it.
62		155
63	=item 3. locks the loop (see below).
64
65	=item 4. creates a new background thread.	156	=item 3. creates a new background thread.
66		157
67	=item 5. runs C<< $loop->run >> in that thread.	158	=item 4. runs C<< $loop->run >> in that thread.
68		159
69	=back	160	=back
		161
		162	The resulting loop will be running and unlocked when it is returned.
		163
		164	Example: create a new loop, block it's interrupt object and embed
		165	it into the foreground L<AnyEvent> event loop. This basically runs the
		166	C<EV::Loop::Async> loop in a synchronous way inside another loop.
		167
		168	my $loop = new EV::Loop::Async 0;
		169	my $async = $loop->interrupt;
		170
		171	$async->block;
		172
		173	my $async_w = AnyEvent->io (
		174	fh => $async->pipe_fileno,
		175	poll => "r",
		176	cb => sub {
		177	# temporarily unblock to handle events
		178	$async->unblock;
		179	$async->block;
		180	},
		181	);
70		182
71	=cut	183	=cut
72		184
73	sub new {	185	sub new {
74	my ($class, $flags, @asy) = @_;	186	my ($class, $flags, @asy) = @_;
…		…
79	$self->_attach ($asy, $asy->signal_func);	191	$self->_attach ($asy, $asy->signal_func);
80		192
81	$self	193	$self
82	}	194	}
83		195
84	=item $loop->nudge	196	=item $loop->notify
85		197
86	Wake up the asynchronous loop. This is useful after registering a new	198	Wake up the asynchronous loop. This is useful after registering a new
87	watcher, to ensure that the background event loop integrates the new	199	watcher, to ensure that the background event loop integrates the new
88	watcher(s) (which only happens when it iterates, which you can force by	200	watcher(s) (which only happens when it iterates, which you can force by
89	calling this method).	201	calling this method).
90		202
91	Without calling this method, the event loop I<eventually> takes notice	203	Without calling this method, the event loop I<eventually> takes notice
92	of new watchers, bit when this happens is not wlel-defined (can be	204	of new watchers, bit when this happens is not well-defined (can be
93	instantaneous, or take a few hours).	205	instantaneous, or take a few hours).
94		206
95	No locking is required.	207	No locking is required.
96		208
97	Example: lock the loop, create a timer, nudge the loop so it takes notice	209	Example: lock the loop, create a timer, nudge the loop so it takes notice
…		…
101	my $flag;	213	my $flag;
102		214
103	{	215	{
104	$loop->scope_lock;	216	$loop->scope_lock;
105	$timer = $loop->timer (1, 0, sub { $flag = 1 });	217	$timer = $loop->timer (1, 0, sub { $flag = 1 });
106	$loop->nudge;	218	$loop->notify;
107	}	219	}
108		220
109	1 until $flag;	221	1 until $flag;
		222
		223	=item $loop->lock
		224
		225	=item $loop->unlock
		226
		227	Lock/unlock the loop data structures. Since the event loop runs in
		228	a separate thread, you have to lock the loop data structures before
		229	accessing them in any way. Since I was lazy, you have to do this manually.
		230
		231	You must lock under the same conditions as you would have to lock the
		232	underlying C library, e.g. when starting or stopping watchers (but not
		233	when creating or destroying them, but note that create and destroy often
		234	starts and stops for you, in which case you have to lock).
		235
		236	When in doubt, lock.
		237
		238	See also the next method, C<< $loop->scope_lock >> for a more failsafe way
		239	to lock parts of your code.
		240
		241	Note that there must be exactly one call of "unblock" for every previous
		242	call to "block" (i.e. calls can nest).
		243
		244	=item $loop->scope_lock
		245
		246	Calls C<lock> immediately, and C<unlock> automatically whent he current
		247	scope is left.
		248
		249	=item $loop->set_max_foreground_loops ($max_loops)
		250
		251	The background loop will immediately stop polling for new events after it
		252	has collected at least one new event, regardless of how long it then takes
		253	to actually handle them.
		254
		255	When Perl finally handles the events, there could be many more ready
		256	file descriptors. To improve latency and performance, you can ask
		257	C<EV::Loop::Async> to loop an additional number of times in the foreground
		258	after invoking the callbacks, effectively doing the polling in the
		259	foreground.
		260
		261	The default is C<0>, meaning that no foreground polling will be done. A
		262	value of C<1> means that, after handling the pending events, it will call
		263	C<< $loop->loop (EV::LOOP_NONBLOCK) >> and handle the resulting events, if
		264	any. A value of C<2> means that this will be iterated twice.
		265
		266	When a foreground event poll does not yield any new events, then no
		267	further iterations will be made, so this is only a I<maximum> value of
		268	additional loop runs.
		269
		270	Take also note of the standard EV C<set_io_collect_interval>
		271	functionality, which can achieve a similar, but different, effect - YMMV.
		272
		273	=back
110		274
111	=head1 SEE ALSO	275	=head1 SEE ALSO
112		276
113	L<EV>, L<Async::Interrupt>.	277	L<EV>, L<Async::Interrupt>.
114		278

Diff Legend

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

Comparing EV-Loop-Async/Async.pm (file contents): Revision 1.1 by root, Tue Jul 14 02:59:55 2009 UTC vs. Revision 1.5 by root, Fri Jul 17 15:06:25 2009 UTC

Diff Legend

Comparing EV-Loop-Async/Async.pm (file contents):
Revision 1.1 by root, Tue Jul 14 02:59:55 2009 UTC vs.
Revision 1.5 by root, Fri Jul 17 15:06:25 2009 UTC