EV-Loop-Async/Async.pm

=head1 NAME

EV::Loop::Async - run an EV event loop asynchronously

=head1 SYNOPSIS

  use EV::Loop::Async;
  
  my $loop = EV::Loop::Async::default;
  my $timer;
  my $flag;
  
  # create a watcher, but make sure the loop is locked
  {
     $loop->scope_lock; # lock the loop structures
     $timer = $loop->timer (5, 1, sub { $flag = 1 });
     $loop->notify; # tell loop to take note of the timer
  }
  
  1 while $flag; # $flag will be set asynchronously
  
  # implement a critical section, uninterrupted by any callbacks
  {
     $loop->interrupt->scope_block;
     # critical section, no watcher callback interruptions
  }
  
  # stop the timer watcher again - locking is required once more
  {
     $loop->scope_lock; # lock the loop structures
     $timer->stop;
     # no need to notify
  }

=head1 DESCRIPTION

This module implements a rather specialised event loop - it takes a normal
L<EV> event loop and runs it in a separate thread. That means it will poll
for events even while your foreground Perl interpreter is busy (you don't
need to have perls pseudo-threads enabled for this either).

Whenever the event loop detecs new events, it will interrupt perl and ask
it to invoke all the pending watcher callbacks. This invocation will be
"synchronous" (in the perl thread), but it can happen at any time.

See the documentation for L<Async::Interrupt> for details on when and how
your perl program can be interrupted (and how to avoid it), and how to
integrate background event loops into foreground ones.

=head1 FAQ

=over 4

=item Why on earth...???

Sometimes you need lower latency for specific events, but it's too heavy
to continuously poll for events. And perl already does this for you
anyways, so this module only uses this existing mechanism.

=item When do I have to lock?

When in doubt, lock. Do not start or stop a watcher, do not create a
watcher (unless with the C<_ns> methods) and do not DESTROY an active
watcher without locking either.

Any other event loop modifications need to be done while locked as
well. So when in doubt, lock (best using C<scope_lock>).

=item Why explicit locking?

Because I was too lazy to wrap everything and there are probably only a
few people on this world using this module.

=back

=head1 FUNCTIONS, METHODS AND VARIABLES OF THIS MODULE

=over 4

=cut

package EV::Loop::Async;

use common::sense;

use EV ();
use Async::Interrupt ();

use base 'EV::Loop';

BEGIN {
   our $VERSION = '0.02';

   require XSLoader;
   XSLoader::load ("EV::Loop::Async", $VERSION);
}

=item $loop = EV::Loop::Async::default

Return the default loop, usable by all programs. The default loop will be
created on the first call to C<default> by calling X<new EV::Loop>, and
should be used by all programs unless they have special requirements.

The associated L<Async::Interrupt> object is stored in
C<$EV::Loop::Async::AI>, and can be used to lock critical sections etc.

=cut

our ($LOOP, $INTERRUPT);

sub default() {
   $LOOP || do {
      $LOOP      = new EV::Loop::Async;
      $INTERRUPT = $LOOP->interrupt;

      $LOOP
   }
}

=item $EV::Loop::Async::LOOP

The default async loop, available after the first call to
C<EV::Loop::Async::default>.

=item $EV::Loop::Async::INTERRUPT

The default loop's L<Async::Interrupt> object, for easy access.

Example: create a section of code where no callback invocations will
interrupt:

   {
      $EV::Loop::Async::INTERRUPT->scope_block;
      # no default loop callbacks will be executed here.
      # the loop will not be locked, however.
   }

=item $loop = new EV::Loop::Async $flags, [Async-Interrupt-Arguments...]

This constructor:

=over 4

=item 1. creates a new C<EV::Loop> (similar C<new EV::Loop>).

=item 2. creates a new L<Async::Interrupt> object and attaches itself to it.

=item 3. creates a new background thread.

=item 4. runs C<< $loop->run >> in that thread.

=back

The resulting loop will be running and unlocked when it is returned.

=cut

sub new {
   my ($class, $flags, @asy) = @_;

   my $self = bless $class->SUPER::new ($flags), $class;
   my ($c_func, $c_arg) = _c_func $self;
   my $asy = new Async::Interrupt @asy, c_cb => [$c_func, $c_arg];
   $self->_attach ($asy, $asy->signal_func);

   $self
}

=item $loop->notify

Wake up the asynchronous loop. This is useful after registering a new
watcher, to ensure that the background event loop integrates the new
watcher(s) (which only happens when it iterates, which you can force by
calling this method).

Without calling this method, the event loop I<eventually> takes notice
of new watchers, bit when this happens is not well-defined (can be
instantaneous, or take a few hours).

No locking is required.

Example: lock the loop, create a timer, nudge the loop so it takes notice
of the new timer, then evily busy-wait till the timer fires.

   my $timer;
   my $flag;

   {
      $loop->scope_lock;
      $timer = $loop->timer (1, 0, sub { $flag = 1 });
      $loop->notify;
   }

   1 until $flag;

=item $loop->lock

=item $loop->unlock

Lock/unlock the loop data structures. Since the event loop runs in
a separate thread, you have to lock the loop data structures before
accessing them in any way. Since I was lazy, you have to do this manually.

You must lock under the same conditions as you would have to lock the
underlying C library, e.g. when starting or stopping watchers (but not
when creating or destroying them, but note that create and destroy often
starts and stops for you, in which case you have to lock).

When in doubt, lock.

See also the next method, C<< $loop->scope_lock >> for a more failsafe way
to lock parts of your code.

Note that there must be exactly one call of "unblock" for every previous
call to "block" (i.e. calls can nest).

=item $loop->scope_lock

Calls C<lock> immediately, and C<unlock> automatically whent he current
scope is left.

=back

=head1 SEE ALSO

L<EV>, L<Async::Interrupt>.

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

1

Revision:	1.3
Committed:	Tue Jul 14 15:09:44 2009 UTC (14 years, 10 months ago) by root
Branch:	MAIN
Changes since 1.2:	+32 -7 lines
Log Message:	* empty log message *
#	Content
1	=head1 NAME
2
3	EV::Loop::Async - run an EV event loop asynchronously
4
5	=head1 SYNOPSIS
6
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	}
34
35	=head1 DESCRIPTION
36
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
77
78	=over 4
79
80	=cut
81
82	package EV::Loop::Async;
83
84	use common::sense;
85
86	use EV ();
87	use Async::Interrupt ();
88
89	use base 'EV::Loop';
90
91	BEGIN {
92	our $VERSION = '0.02';
93
94	require XSLoader;
95	XSLoader::load ("EV::Loop::Async", $VERSION);
96	}
97
98	=item $loop = EV::Loop::Async::default
99
100	Return the default loop, usable by all programs. The default loop will be
101	created on the first call to C<default> by calling X<new EV::Loop>, and
102	should be used by all programs unless they have special requirements.
103
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.
106
107	=cut
108
109	our ($LOOP, $INTERRUPT);
110
111	sub default() {
112	$LOOP \|\| do {
113	$LOOP = new EV::Loop::Async;
114	$INTERRUPT = $LOOP->interrupt;
115
116	$LOOP
117	}
118	}
119
120	=item $EV::Loop::Async::LOOP
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	=item $loop = new EV::Loop::Async $flags, [Async-Interrupt-Arguments...]
139
140	This constructor:
141
142	=over 4
143
144	=item 1. creates a new C<EV::Loop> (similar C<new EV::Loop>).
145
146	=item 2. creates a new L<Async::Interrupt> object and attaches itself to it.
147
148	=item 3. creates a new background thread.
149
150	=item 4. runs C<< $loop->run >> in that thread.
151
152	=back
153
154	The resulting loop will be running and unlocked when it is returned.
155
156	=cut
157
158	sub new {
159	my ($class, $flags, @asy) = @_;
160
161	my $self = bless $class->SUPER::new ($flags), $class;
162	my ($c_func, $c_arg) = _c_func $self;
163	my $asy = new Async::Interrupt @asy, c_cb => [$c_func, $c_arg];
164	$self->_attach ($asy, $asy->signal_func);
165
166	$self
167	}
168
169	=item $loop->notify
170
171	Wake up the asynchronous loop. This is useful after registering a new
172	watcher, to ensure that the background event loop integrates the new
173	watcher(s) (which only happens when it iterates, which you can force by
174	calling this method).
175
176	Without calling this method, the event loop I<eventually> takes notice
177	of new watchers, bit when this happens is not well-defined (can be
178	instantaneous, or take a few hours).
179
180	No locking is required.
181
182	Example: lock the loop, create a timer, nudge the loop so it takes notice
183	of the new timer, then evily busy-wait till the timer fires.
184
185	my $timer;
186	my $flag;
187
188	{
189	$loop->scope_lock;
190	$timer = $loop->timer (1, 0, sub { $flag = 1 });
191	$loop->notify;
192	}
193
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
223
224	=head1 SEE ALSO
225
226	L<EV>, L<Async::Interrupt>.
227
228	=head1 AUTHOR
229
230	Marc Lehmann <schmorp@schmorp.de>
231	http://home.schmorp.de/
232
233	=cut
234
235	1
236