[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.3 by root, Tue Jul 14 15:09:44 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
53	=item $loop = new EV::Loop $flags, [Async-Interrupt-Arguments...]	138	=item $loop = new EV::Loop::Async $flags, [Async-Interrupt-Arguments...]
54		139
55	This constructor:	140	This constructor:
56		141
57	=over 4	142	=over 4
58		143
59	=item 1. creates a new C<EV::Loop> (similar C<new EV::Loop>).	144	=item 1. creates a new C<EV::Loop> (similar C<new EV::Loop>).
60		145
61	=item 2. creates a new L<Async::Interrupt> object and attaches itself to it.	146	=item 2. creates a new L<Async::Interrupt> object and attaches itself to it.
62		147
63	=item 3. locks the loop (see below).
64
65	=item 4. creates a new background thread.	148	=item 3. creates a new background thread.
66		149
67	=item 5. runs C<< $loop->run >> in that thread.	150	=item 4. runs C<< $loop->run >> in that thread.
68		151
69	=back	152	=back
		153
		154	The resulting loop will be running and unlocked when it is returned.
70		155
71	=cut	156	=cut
72		157
73	sub new {	158	sub new {
74	my ($class, $flags, @asy) = @_;	159	my ($class, $flags, @asy) = @_;
…		…
79	$self->_attach ($asy, $asy->signal_func);	164	$self->_attach ($asy, $asy->signal_func);
80		165
81	$self	166	$self
82	}	167	}
83		168
84	=item $loop->nudge	169	=item $loop->notify
85		170
86	Wake up the asynchronous loop. This is useful after registering a new	171	Wake up the asynchronous loop. This is useful after registering a new
87	watcher, to ensure that the background event loop integrates the new	172	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	173	watcher(s) (which only happens when it iterates, which you can force by
89	calling this method).	174	calling this method).
90		175
91	Without calling this method, the event loop I<eventually> takes notice	176	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	177	of new watchers, bit when this happens is not well-defined (can be
93	instantaneous, or take a few hours).	178	instantaneous, or take a few hours).
94		179
95	No locking is required.	180	No locking is required.
96		181
97	Example: lock the loop, create a timer, nudge the loop so it takes notice	182	Example: lock the loop, create a timer, nudge the loop so it takes notice
…		…
101	my $flag;	186	my $flag;
102		187
103	{	188	{
104	$loop->scope_lock;	189	$loop->scope_lock;
105	$timer = $loop->timer (1, 0, sub { $flag = 1 });	190	$timer = $loop->timer (1, 0, sub { $flag = 1 });
106	$loop->nudge;	191	$loop->notify;
107	}	192	}
108		193
109	1 until $flag;	194	1 until $flag;
		195
		196	=item $loop->lock
		197
		198	=item $loop->unlock
		199
		200	Lock/unlock the loop data structures. Since the event loop runs in
		201	a separate thread, you have to lock the loop data structures before
		202	accessing them in any way. Since I was lazy, you have to do this manually.
		203
		204	You must lock under the same conditions as you would have to lock the
		205	underlying C library, e.g. when starting or stopping watchers (but not
		206	when creating or destroying them, but note that create and destroy often
		207	starts and stops for you, in which case you have to lock).
		208
		209	When in doubt, lock.
		210
		211	See also the next method, C<< $loop->scope_lock >> for a more failsafe way
		212	to lock parts of your code.
		213
		214	Note that there must be exactly one call of "unblock" for every previous
		215	call to "block" (i.e. calls can nest).
		216
		217	=item $loop->scope_lock
		218
		219	Calls C<lock> immediately, and C<unlock> automatically whent he current
		220	scope is left.
		221
		222	=back
110		223
111	=head1 SEE ALSO	224	=head1 SEE ALSO
112		225
113	L<EV>, L<Async::Interrupt>.	226	L<EV>, L<Async::Interrupt>.
114		227

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.3 by root, Tue Jul 14 15:09:44 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.3 by root, Tue Jul 14 15:09:44 2009 UTC