ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/EV-Loop-Async/Async.pm
(Generate patch)

Comparing EV-Loop-Async/Async.pm (file contents):
Revision 1.1 by root, Tue Jul 14 02:59:55 2009 UTC vs.
Revision 1.2 by root, Tue Jul 14 13:24:34 2009 UTC

… …
2 2
3EV::Loop::Async - run an EV event loop asynchronously 3EV::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 {
14 $loop->scope_lock; # lock the loop structures
15 $timer = $loop->timer (5, 1, sub { $flag = 1 });
16 $loop->nudge; # tell loop to take note of the timer
17 }
18
19 1 while $flag; # $flag will be set asynchronously
20
21 {
22 $loop->interrupt->scope_block;
23 # critical section, no watcher callback interruptions
24 }
25
26 # stop timer again
27
28 {
29 $loop->scope_lock; # lock the loop structures
30 $timer->stop;
31 # no need to nudge
32 }
8 33
9=head1 DESCRIPTION 34=head1 DESCRIPTION
10 35
11TODO. 36This module implements a rather specialised event loop - it takes a normal
37L<EV> event loop and runs it in a separate thread. That means it will poll
38for events even while your foreground Perl interpreter is busy (you don't
39need to have perls pseudo-threads enabled for this either).
40
41Whenever the event loop detecs new events, it will interrupt perl and ask
42it to invoke all the pending watcher callbacks. This invocation will be
43"synchronous" (in the perl thread), but it can happen at any time.
44
45See the documentation for L<Async::Interrupt> for details on when and how
46your perl program can be interrupted (and how to avoid it), and how to
47integrate background event loops into foreground ones.
48
49=head1 FAQ
50
51=head1 FUNCTIONS, METHODS AND VARIABLES OF THIS MODULE
12 52
13=over 4 53=over 4
14 54
15=cut 55=cut
16 56
… …
34 74
35Return the default loop, usable by all programs. The default loop will be 75Return the default loop, usable by all programs. The default loop will be
36created on the first call to C<default> by calling X<new EV::Loop>, and 76created on the first call to C<default> by calling X<new EV::Loop>, and
37should be used by all programs unless they have special requirements. 77should be used by all programs unless they have special requirements.
38 78
39=cut 79The associated L<Async::Interrupt> object is stored in
80C<$EV::Loop::Async::AI>, and can be used to lock critical sections etc.
40 81
41our ($LOOP, $ASYNC); 82=cut
83
84our ($LOOP, $INTERRUPT);
42 85
43sub default() { 86sub default() {
44 $LOOP || do { 87 $LOOP || do {
45 $LOOP = new EV::Loop::Async; 88 $LOOP = new EV::Loop::Async;
46# $ASYNC = $LOOP->async; 89 $INTERRUPT = $LOOP->interrupt;
47 90
48 $LOOP 91 $LOOP
49 } 92 }
50} 93}
51 94
95=item $EV::Loop::Async::LOOP
52 96
97The default async loop, available after the first call to
98C<EV::Loop::Async::default>.
99
100=item $EV::Loop::Async::INTERRUPT
101
102The default loop's L<Async::Interrupt> object, for easy access.
103
104Example: create a section of code where no callback invocations will
105interrupt:
106
107 {
108 $EV::Loop::Async::INTERRUPT->scope_block;
109 # no default loop callbacks will be executed here.
110 # the loop will not be locked, however.
111 }
112
53=item $loop = new EV::Loop $flags, [Async-Interrupt-Arguments...] 113=item $loop = new EV::Loop::Async $flags, [Async-Interrupt-Arguments...]
54 114
55This constructor: 115This constructor:
56 116
57=over 4 117=over 4
58 118
59=item 1. creates a new C<EV::Loop> (similar C<new EV::Loop>). 119=item 1. creates a new C<EV::Loop> (similar C<new EV::Loop>).
60 120
61=item 2. creates a new L<Async::Interrupt> object and attaches itself to it. 121=item 2. creates a new L<Async::Interrupt> object and attaches itself to it.
62 122
63=item 3. locks the loop (see below).
64
65=item 4. creates a new background thread. 123=item 3. creates a new background thread.
66 124
67=item 5. runs C<< $loop->run >> in that thread. 125=item 4. runs C<< $loop->run >> in that thread.
68 126
69=back 127=back
128
129The resulting loop will be running and unlocked when it is returned.
70 130
71=cut 131=cut
72 132
73sub new { 133sub new {
74 my ($class, $flags, @asy) = @_; 134 my ($class, $flags, @asy) = @_;
… …
106 $loop->nudge; 166 $loop->nudge;
107 } 167 }
108 168
109 1 until $flag; 169 1 until $flag;
110 170
171=item $loop->lock
172
173=item $loop->unlock
174
175Lock/unlock the loop data structures. Since the event loop runs in
176a separate thread, you have to lock the loop data structures before
177accessing them in any way. Since I was lazy, you have to do this manually.
178
179You must lock under the same conditions as you would have to lock the
180underlying C library, e.g. when starting or stopping watchers (but not
181when creating or destroying them, but note that create and destroy often
182starts and stops for you, in which case you have to lock).
183
184When in doubt, lock.
185
186See also the next method, C<< $loop->scope_lock >> for a more failsafe way
187to lock parts of your code.
188
189Note that there must be exactly one call of "unblock" for every previous
190call to "block" (i.e. calls can nest).
191
192=item $loop->scope_lock
193
194Calls C<lock> immediately, and C<unlock> automatically whent he current
195scope is left.
196
197=back
198
111=head1 SEE ALSO 199=head1 SEE ALSO
112 200
113L<EV>, L<Async::Interrupt>. 201L<EV>, L<Async::Interrupt>.
114 202
115=head1 AUTHOR 203=head1 AUTHOR

Diff Legend

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