Coro/Coro/AnyEvent.pm

=head1 NAME

Coro::AnyEvent - integrate threads into AnyEvent

=head1 SYNOPSIS

 use Coro;
 use AnyEvent;
 # using both Coro and AnyEvent will automatically load Coro::AnyEvent

 # or load it manually for it's utility functions:
 use Coro::AnyEvent;

 Coro::AnyEvent::sleep 5;     # block current thread for 5s
 Coro::AnyEvent::poll;        # poll for new events once
 Coro::AnyEvent::idle;        # block until process no longer busy
 Coro::AnyEvent::idle_upto 5; # same, but only up to 5 seconds

 Coro::AnyEvent::readable $fh, 60
    or die "fh didn't become readable within 60 seconds\n";

=head1 DESCRIPTION

When one naively starts to use threads in Perl, one will quickly run
into the problem that threads that block on a syscall (sleeping,
reading from a socket etc.) will block all threads.

If one then uses an event loop, the problem is that the event loop has
no knowledge of threads and will not run them before it polls for new
events, again blocking the whole process.

This module integrates threads into any event loop supported by
AnyEvent, combining event-based programming with coroutine-based
programming in a natural way.

As of Coro 5.21 and newer, this module gets loaded automatically when
AnyEvent initialises itself and Coro is used in the same process, thus
there is no need to load it manually if you just want your threads to
coexist with AnyEvent.

If you want to use any functions from this module, you of course still
need to C<use Coro::AnyEvent>, just as with other perl modules.

Also, this module autodetects the event loop used (by relying on
L<AnyEvent>) and will either automatically defer to the high-performance
L<Coro::EV> or L<Coro::Event> modules, or will use a generic integration
method that should work with any event loop supported by L<AnyEvent>.

=head1 USAGE

=head2 RUN AN EVENT LOOP - OR NOT?

For performance reasons, it is recommended that the main program or
something else runs the event loop of the event model you use, i.e.

   use Gtk2; # <- the event model
   use AnyEvent;
   use Coro:

   # initialise stuff
   async { ... };

   # now run mainloop of Gtk2
   main Gtk2;

You can move the event loop into a thread as well, although this tends to
get confusing:

   use Gtk2;
   use AnyEvent;
   use Coro:

   async { main Gtk2 };

   # do other things...
   while () {
      use Coro::AnyEvent;
      Coro::AnyEvent::sleep 1;
      print "ping...\n";
   }

You can also do nothing, in which case Coro:AnyEvent will invoke the event
loop as needed, which is less efficient, but sometimes very convenient.

What you I<MUST NOT DO EVER> is to block inside an event loop
callback. The reason is that most event loops are not reentrant and this
can cause a deadlock at best and corrupt memory at worst.

Coro will try to catch you when you block in the event loop
("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and
only works when you do not run your own event loop.

To avoid this problem, simply do not block inside an event callback
- start a new thread (e.g. with C<Coro:async_pool>) or use
C<Coro::unblock_sub>.

=head2 INVERSION OF CONTROL

If you need to wait for a single event, the rouse functions will come in
handy (see the Coro manpage for details):

   # wait for single SIGINT
   {
      my $int_w = AnyEvent->signal (signal => "INT", cb => Coro::rouse_cb);
      Coro::rouse_wait;
   }

=head2 EVENT MODULES OTHER THEN ANYEVENT

Keep in mind that, as shipped, Coro and Coro::AnyEvent only work with
AnyEvent, and only when AnyEvent is actually used (i.e. initialised), so
this will not work:

   # does not work: EV without AnyEvent is not recognised
   use EV;
   use Coro;

   EV::loop;

And neither does this, unless you actually I<use> AnyEvent for something:

   # does not work: AnyEvent must be initialised (e.g. by creating watchers)
   use EV;
   use AnyEvent;
   use Coro;

   EV::loop;

This does work, however, because you create a watcher (condvars work,
too), thus forcing AnyEvent to initialise itself:

   # does work: AnyEvent is actually used
   use EV;
   use AnyEvent;
   use Coro;

   my $timer = AE::timer 1, 1, sub { };

   EV::loop;

And if you want to use AnyEvent just to bridge between Coro and your event
model of choice, you can simply force it to initialise itself, like this:

   # does work: AnyEvent is initialised manually
   use POE;
   use AnyEvent;
   use Coro;

   AnyEvent::detect; # force AnyEvent to integrate Coro into POE
   POE::Kernel->run;

=head1 FUNCTIONS

Coro::AnyEvent also offers a few functions that might be useful.

=over 4

=cut

package Coro::AnyEvent;

use common::sense;

use Coro;
use AnyEvent ();

our $VERSION = 6.02;

#############################################################################
# idle handler

our $IDLE;

#############################################################################
# 0-timeout idle emulation watcher

our $ACTIVITY;

sub _activity {
   $ACTIVITY ||= AE::timer 0, 0, \&_schedule;
}

Coro::_set_readyhook (\&AnyEvent::detect);

AnyEvent::post_detect {
   unshift @AnyEvent::CondVar::ISA, "Coro::AnyEvent::CondVar";

   my $model = $AnyEvent::MODEL;

   if ($model eq "AnyEvent::Impl::EV" and eval { require Coro::EV }) {
      # provide faster versions of some functions
      Coro::EV::_set_readyhook ();

      eval '
         *sleep = \&Coro::EV::timer_once;
         *poll  = \&Coro::EV::_poll;
         *idle  = sub() {
            my $w = EV::idle Coro::rouse_cb;
            Coro::rouse_wait;
         };
         *idle_upto = sub($) {
            my $cb = Coro::rouse_cb;
            my $t = EV::timer $_[0], 0, $cb;
            my $w = EV::idle $cb;
            Coro::rouse_wait;
         };
         *readable = sub($;$) {
            EV::READ  & Coro::EV::timed_io_once $_[0], EV::READ , $_[1]
         };
         *writable = sub($;$) {
            EV::WRITE & Coro::EV::timed_io_once $_[0], EV::WRITE, $_[1]
         };
      ';
      die if $@;

   } elsif ($model eq "AnyEvent::Impl::Event" and eval { require Coro::Event }) {
      Coro::_set_readyhook undef;
      # let Coro::Event do its thing
   } else {
      # do the inefficient thing ourselves
      Coro::_set_readyhook \&_activity;

      $IDLE = new Coro sub {
         my $one_event = AnyEvent->can ("one_event");

         while () {
            $one_event->();
            Coro::schedule if Coro::nready;
         }
      };
      $IDLE->{desc} = "[AnyEvent idle process]";

      $Coro::idle = $IDLE;

      # call the readyhook, in case coroutines were already readied
      _activity;
   }
};

=item Coro::AnyEvent::poll

This call will block the current thread until the event loop has polled
for potential new events and instructs the event loop to poll for new
events once, without blocking.

Note that this call will not actually execute the poll, nor will it wait
until there are some events, just block until the event loop has polled
for new events, so other threads will have a chance to run.

This is useful when you have a thread that does some computations, but you
still want to poll for new events from time to time. Simply call C<poll>
from time to time:

   my $long_calc = async {
      for (1..10000) {
         Coro::AnyEvent::poll:
         # do some stuff, make sure it takes at least 0.001s or so
      }
   }

Although you should also consider C<idle> or C<idle_upto> in such cases.

=item Coro::AnyEvent::sleep $seconds

This blocks the current thread for at least the given number of seconds.

=item Coro::AnyEvent::idle

This call is similar to C<poll> in that it will also poll for
events. Unlike C<poll>, it will only resume the thread once there are no
events to handle anymore, i.e. when the process is otherwise idle.

This is good for background threads that shouldn't use CPU time when
foreground jobs are ready to run.

=item Coro::AnyEvent::idle_upto $seconds

Like C<idle>, but with a maximum waiting time.

If your process is busy handling events, calling C<idle> can mean that
your thread will never be resumed. To avoid this, you can use C<idle_upto>
and specify a timeout, after which your thread will be resumed even if the
process is completely busy.

=item Coro::AnyEvent::readable $fh_or_fileno[, $timeout]

=item Coro::AnyEvent::writable $fh_or_fileno[, $timeout]

Blocks the current thread until the given file handle (or file descriptor)
becomes readable (or writable), or the given timeout has elapsed,
whichever happens first. No timeout counts as infinite timeout.

Returns true when the file handle became ready, false when a timeout
occured.

Note that these functions are quite inefficient as compared to using a
single watcher (they recreate watchers on every invocation) or compared to
using Coro::Handle.

Note also that they only work for sources that have reasonable
non-blocking behaviour (e.g. not files).

Example: wait until STDIN becomes readable, then quit the program.

   use Coro::AnyEvent;
   print "press enter to quit...\n";
   Coro::AnyEvent::readable *STDIN;
   exit 0;

=cut

sub poll() {
   my $w = AE::timer 0, 0, Coro::rouse_cb;
   Coro::rouse_wait;
}

sub sleep($) {
   my $w = AE::timer $_[0], 0, Coro::rouse_cb;
   Coro::rouse_wait;
}

sub idle() {
   my $w = AE::idle Coro::rouse_cb;
   Coro::rouse_wait;
}

sub idle_upto($) {
   my $cb = Coro::rouse_cb;
   my $t = AE::timer shift, 0, $cb;
   my $w = AE::idle $cb;
   Coro::rouse_wait;
}

sub readable($;$) {
   my $cb = Coro::rouse_cb;
   my $w = AE::io $_[0], 0, sub { $cb->(1) };
   my $t = defined $_[1] && AE::timer $_[1], 0, sub { $cb->(0) };
   Coro::rouse_wait
}

sub writable($;$) {
   my $cb = Coro::rouse_cb;
   my $w = AE::io $_[0], 1, sub { $cb->(1) };
   my $t = defined $_[1] && AE::timer $_[1], 0, sub { $cb->(0) };
   Coro::rouse_wait
}

#############################################################################
# override condvars

package Coro::AnyEvent::CondVar;

sub _send {
   (delete $_[0]{_ae_coro})->ready if $_[0]{_ae_coro};
}

sub _wait {
   while (!$_[0]{_ae_sent}) {
      local $_[0]{_ae_coro} = $Coro::current;
      Coro::schedule;
   }
}

1;

=back

=head1 IMPLEMENTATION DETAILS

Unfortunately, few event loops (basically only L<EV> and L<Event>)
support the kind of integration required for smooth operations well, and
consequently, AnyEvent cannot completely offer the functionality required
by this module, so we need to improvise.

Here is what this module does when it has to work with other event loops:

=over 4

=item * run ready threads before blocking the process

Each time a thread is put into the ready queue (and there are no other
threads in the ready queue), a timer with an C<after> value of C<0> is
registered with AnyEvent.

This creates something similar to an I<idle> watcher, i.e. a watcher
that keeps the event loop from blocking but still polls for new
events. (Unfortunately, some badly designed event loops (e.g. Event::Lib)
don't support a timeout of C<0> and will always block for a bit).

The callback for that timer will C<cede> to other threads of the same or
higher priority for as long as such threads exists. This has the effect of
running all threads that have work to do until all threads block to wait
for external events.

If no threads of equal or higher priority are ready, it will cede to any
thread, but only once. This has the effect of running lower-priority
threads as well, but it will not keep higher priority threads from
receiving new events.

The priority used is simply the priority of the thread that runs the event
loop, usually the main program, which usually has a priority of C<0>. Note
that Coro::AnyEvent does I<not> run an event loop for you, so unless the
main program runs one, there will simply be no event loop to C<cede> to
(event handling will still work, somewhat inefficiently, but any thread
will have a higher priority than event handling in that case).

=item * provide a suitable idle callback.

In addition to hooking into C<ready>, this module will also provide a
C<$Coro::idle> handler that runs the event loop. It is best not to take
advantage of this too often, as this is rather inefficient, but it should
work perfectly fine.

=item * provide overrides for AnyEvent's condvars

This module installs overrides for AnyEvent's condvars. That is, when
the module is loaded it will provide its own condition variables. This
makes them coroutine-safe, i.e. you can safely block on them from within a
coroutine.

=item * lead to data corruption or worse

As C<unblock_sub> cannot be used by this module (as it is the module
that implements it, basically), you must not call into the event
loop recursively from any coroutine. This is not usually a difficult
restriction to live with, just use condvars, C<unblock_sub> or other means
of inter-coroutine-communications.

If you use a module that supports AnyEvent (or uses the same event loop
as AnyEvent, making the compatible), and it offers callbacks of any kind,
then you must not block in them, either (or use e.g. C<unblock_sub>), see
the description of C<unblock_sub> in the L<Coro> module.

This also means that you should load the module as early as possible,
as only condvars created after this module has been loaded will work
correctly.

=back

=head1 SEE ALSO

L<AnyEvent>, to see which event loops are supported, L<Coro::EV> and
L<Coro::Event> for more efficient and more correct solutions (they will be
used automatically if applicable).

=head1 AUTHOR

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

=cut

Revision:	1.71
Committed:	Wed Jul 13 02:36:02 2011 UTC (12 years, 11 months ago) by root
Branch:	MAIN
CVS Tags:	rel-6_02
Changes since 1.70:	+1 -1 lines
Log Message:	6.02
#	Content
1	=head1 NAME
2
3	Coro::AnyEvent - integrate threads into AnyEvent
4
5	=head1 SYNOPSIS
6
7	use Coro;
8	use AnyEvent;
9	# using both Coro and AnyEvent will automatically load Coro::AnyEvent
10
11	# or load it manually for it's utility functions:
12	use Coro::AnyEvent;
13
14	Coro::AnyEvent::sleep 5; # block current thread for 5s
15	Coro::AnyEvent::poll; # poll for new events once
16	Coro::AnyEvent::idle; # block until process no longer busy
17	Coro::AnyEvent::idle_upto 5; # same, but only up to 5 seconds
18
19	Coro::AnyEvent::readable $fh, 60
20	or die "fh didn't become readable within 60 seconds\n";
21
22	=head1 DESCRIPTION
23
24	When one naively starts to use threads in Perl, one will quickly run
25	into the problem that threads that block on a syscall (sleeping,
26	reading from a socket etc.) will block all threads.
27
28	If one then uses an event loop, the problem is that the event loop has
29	no knowledge of threads and will not run them before it polls for new
30	events, again blocking the whole process.
31
32	This module integrates threads into any event loop supported by
33	AnyEvent, combining event-based programming with coroutine-based
34	programming in a natural way.
35
36	As of Coro 5.21 and newer, this module gets loaded automatically when
37	AnyEvent initialises itself and Coro is used in the same process, thus
38	there is no need to load it manually if you just want your threads to
39	coexist with AnyEvent.
40
41	If you want to use any functions from this module, you of course still
42	need to C<use Coro::AnyEvent>, just as with other perl modules.
43
44	Also, this module autodetects the event loop used (by relying on
45	L<AnyEvent>) and will either automatically defer to the high-performance
46	L<Coro::EV> or L<Coro::Event> modules, or will use a generic integration
47	method that should work with any event loop supported by L<AnyEvent>.
48
49	=head1 USAGE
50
51	=head2 RUN AN EVENT LOOP - OR NOT?
52
53	For performance reasons, it is recommended that the main program or
54	something else runs the event loop of the event model you use, i.e.
55
56	use Gtk2; # <- the event model
57	use AnyEvent;
58	use Coro:
59
60	# initialise stuff
61	async { ... };
62
63	# now run mainloop of Gtk2
64	main Gtk2;
65
66	You can move the event loop into a thread as well, although this tends to
67	get confusing:
68
69	use Gtk2;
70	use AnyEvent;
71	use Coro:
72
73	async { main Gtk2 };
74
75	# do other things...
76	while () {
77	use Coro::AnyEvent;
78	Coro::AnyEvent::sleep 1;
79	print "ping...\n";
80	}
81
82	You can also do nothing, in which case Coro:AnyEvent will invoke the event
83	loop as needed, which is less efficient, but sometimes very convenient.
84
85	What you I<MUST NOT DO EVER> is to block inside an event loop
86	callback. The reason is that most event loops are not reentrant and this
87	can cause a deadlock at best and corrupt memory at worst.
88
89	Coro will try to catch you when you block in the event loop
90	("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and
91	only works when you do not run your own event loop.
92
93	To avoid this problem, simply do not block inside an event callback
94	- start a new thread (e.g. with C<Coro:async_pool>) or use
95	C<Coro::unblock_sub>.
96
97	=head2 INVERSION OF CONTROL
98
99	If you need to wait for a single event, the rouse functions will come in
100	handy (see the Coro manpage for details):
101
102	# wait for single SIGINT
103	{
104	my $int_w = AnyEvent->signal (signal => "INT", cb => Coro::rouse_cb);
105	Coro::rouse_wait;
106	}
107
108	=head2 EVENT MODULES OTHER THEN ANYEVENT
109
110	Keep in mind that, as shipped, Coro and Coro::AnyEvent only work with
111	AnyEvent, and only when AnyEvent is actually used (i.e. initialised), so
112	this will not work:
113
114	# does not work: EV without AnyEvent is not recognised
115	use EV;
116	use Coro;
117
118	EV::loop;
119
120	And neither does this, unless you actually I<use> AnyEvent for something:
121
122	# does not work: AnyEvent must be initialised (e.g. by creating watchers)
123	use EV;
124	use AnyEvent;
125	use Coro;
126
127	EV::loop;
128
129	This does work, however, because you create a watcher (condvars work,
130	too), thus forcing AnyEvent to initialise itself:
131
132	# does work: AnyEvent is actually used
133	use EV;
134	use AnyEvent;
135	use Coro;
136
137	my $timer = AE::timer 1, 1, sub { };
138
139	EV::loop;
140
141	And if you want to use AnyEvent just to bridge between Coro and your event
142	model of choice, you can simply force it to initialise itself, like this:
143
144	# does work: AnyEvent is initialised manually
145	use POE;
146	use AnyEvent;
147	use Coro;
148
149	AnyEvent::detect; # force AnyEvent to integrate Coro into POE
150	POE::Kernel->run;
151
152	=head1 FUNCTIONS
153
154	Coro::AnyEvent also offers a few functions that might be useful.
155
156	=over 4
157
158	=cut
159
160	package Coro::AnyEvent;
161
162	use common::sense;
163
164	use Coro;
165	use AnyEvent ();
166
167	our $VERSION = 6.02;
168
169	#############################################################################
170	# idle handler
171
172	our $IDLE;
173
174	#############################################################################
175	# 0-timeout idle emulation watcher
176
177	our $ACTIVITY;
178
179	sub _activity {
180	$ACTIVITY \|\|= AE::timer 0, 0, \&_schedule;
181	}
182
183	Coro::_set_readyhook (\&AnyEvent::detect);
184
185	AnyEvent::post_detect {
186	unshift @AnyEvent::CondVar::ISA, "Coro::AnyEvent::CondVar";
187
188	my $model = $AnyEvent::MODEL;
189
190	if ($model eq "AnyEvent::Impl::EV" and eval { require Coro::EV }) {
191	# provide faster versions of some functions
192	Coro::EV::_set_readyhook ();
193
194	eval '
195	*sleep = \&Coro::EV::timer_once;
196	*poll = \&Coro::EV::_poll;
197	*idle = sub() {
198	my $w = EV::idle Coro::rouse_cb;
199	Coro::rouse_wait;
200	};
201	*idle_upto = sub($) {
202	my $cb = Coro::rouse_cb;
203	my $t = EV::timer $_[0], 0, $cb;
204	my $w = EV::idle $cb;
205	Coro::rouse_wait;
206	};
207	*readable = sub($;$) {
208	EV::READ & Coro::EV::timed_io_once $_[0], EV::READ , $_[1]
209	};
210	*writable = sub($;$) {
211	EV::WRITE & Coro::EV::timed_io_once $_[0], EV::WRITE, $_[1]
212	};
213	';
214	die if $@;
215
216	} elsif ($model eq "AnyEvent::Impl::Event" and eval { require Coro::Event }) {
217	Coro::_set_readyhook undef;
218	# let Coro::Event do its thing
219	} else {
220	# do the inefficient thing ourselves
221	Coro::_set_readyhook \&_activity;
222
223	$IDLE = new Coro sub {
224	my $one_event = AnyEvent->can ("one_event");
225
226	while () {
227	$one_event->();
228	Coro::schedule if Coro::nready;
229	}
230	};
231	$IDLE->{desc} = "[AnyEvent idle process]";
232
233	$Coro::idle = $IDLE;
234
235	# call the readyhook, in case coroutines were already readied
236	_activity;
237	}
238	};
239
240	=item Coro::AnyEvent::poll
241
242	This call will block the current thread until the event loop has polled
243	for potential new events and instructs the event loop to poll for new
244	events once, without blocking.
245
246	Note that this call will not actually execute the poll, nor will it wait
247	until there are some events, just block until the event loop has polled
248	for new events, so other threads will have a chance to run.
249
250	This is useful when you have a thread that does some computations, but you
251	still want to poll for new events from time to time. Simply call C<poll>
252	from time to time:
253
254	my $long_calc = async {
255	for (1..10000) {
256	Coro::AnyEvent::poll:
257	# do some stuff, make sure it takes at least 0.001s or so
258	}
259	}
260
261	Although you should also consider C<idle> or C<idle_upto> in such cases.
262
263	=item Coro::AnyEvent::sleep $seconds
264
265	This blocks the current thread for at least the given number of seconds.
266
267	=item Coro::AnyEvent::idle
268
269	This call is similar to C<poll> in that it will also poll for
270	events. Unlike C<poll>, it will only resume the thread once there are no
271	events to handle anymore, i.e. when the process is otherwise idle.
272
273	This is good for background threads that shouldn't use CPU time when
274	foreground jobs are ready to run.
275
276	=item Coro::AnyEvent::idle_upto $seconds
277
278	Like C<idle>, but with a maximum waiting time.
279
280	If your process is busy handling events, calling C<idle> can mean that
281	your thread will never be resumed. To avoid this, you can use C<idle_upto>
282	and specify a timeout, after which your thread will be resumed even if the
283	process is completely busy.
284
285	=item Coro::AnyEvent::readable $fh_or_fileno[, $timeout]
286
287	=item Coro::AnyEvent::writable $fh_or_fileno[, $timeout]
288
289	Blocks the current thread until the given file handle (or file descriptor)
290	becomes readable (or writable), or the given timeout has elapsed,
291	whichever happens first. No timeout counts as infinite timeout.
292
293	Returns true when the file handle became ready, false when a timeout
294	occured.
295
296	Note that these functions are quite inefficient as compared to using a
297	single watcher (they recreate watchers on every invocation) or compared to
298	using Coro::Handle.
299
300	Note also that they only work for sources that have reasonable
301	non-blocking behaviour (e.g. not files).
302
303	Example: wait until STDIN becomes readable, then quit the program.
304
305	use Coro::AnyEvent;
306	print "press enter to quit...\n";
307	Coro::AnyEvent::readable *STDIN;
308	exit 0;
309
310	=cut
311
312	sub poll() {
313	my $w = AE::timer 0, 0, Coro::rouse_cb;
314	Coro::rouse_wait;
315	}
316
317	sub sleep($) {
318	my $w = AE::timer $_[0], 0, Coro::rouse_cb;
319	Coro::rouse_wait;
320	}
321
322	sub idle() {
323	my $w = AE::idle Coro::rouse_cb;
324	Coro::rouse_wait;
325	}
326
327	sub idle_upto($) {
328	my $cb = Coro::rouse_cb;
329	my $t = AE::timer shift, 0, $cb;
330	my $w = AE::idle $cb;
331	Coro::rouse_wait;
332	}
333
334	sub readable($;$) {
335	my $cb = Coro::rouse_cb;
336	my $w = AE::io $_[0], 0, sub { $cb->(1) };
337	my $t = defined $_[1] && AE::timer $_[1], 0, sub { $cb->(0) };
338	Coro::rouse_wait
339	}
340
341	sub writable($;$) {
342	my $cb = Coro::rouse_cb;
343	my $w = AE::io $_[0], 1, sub { $cb->(1) };
344	my $t = defined $_[1] && AE::timer $_[1], 0, sub { $cb->(0) };
345	Coro::rouse_wait
346	}
347
348	#############################################################################
349	# override condvars
350
351	package Coro::AnyEvent::CondVar;
352
353	sub _send {
354	(delete $_[0]{_ae_coro})->ready if $_[0]{_ae_coro};
355	}
356
357	sub _wait {
358	while (!$_[0]{_ae_sent}) {
359	local $_[0]{_ae_coro} = $Coro::current;
360	Coro::schedule;
361	}
362	}
363
364	1;
365
366	=back
367
368	=head1 IMPLEMENTATION DETAILS
369
370	Unfortunately, few event loops (basically only L<EV> and L<Event>)
371	support the kind of integration required for smooth operations well, and
372	consequently, AnyEvent cannot completely offer the functionality required
373	by this module, so we need to improvise.
374
375	Here is what this module does when it has to work with other event loops:
376
377	=over 4
378
379	=item * run ready threads before blocking the process
380
381	Each time a thread is put into the ready queue (and there are no other
382	threads in the ready queue), a timer with an C<after> value of C<0> is
383	registered with AnyEvent.
384
385	This creates something similar to an I<idle> watcher, i.e. a watcher
386	that keeps the event loop from blocking but still polls for new
387	events. (Unfortunately, some badly designed event loops (e.g. Event::Lib)
388	don't support a timeout of C<0> and will always block for a bit).
389
390	The callback for that timer will C<cede> to other threads of the same or
391	higher priority for as long as such threads exists. This has the effect of
392	running all threads that have work to do until all threads block to wait
393	for external events.
394
395	If no threads of equal or higher priority are ready, it will cede to any
396	thread, but only once. This has the effect of running lower-priority
397	threads as well, but it will not keep higher priority threads from
398	receiving new events.
399
400	The priority used is simply the priority of the thread that runs the event
401	loop, usually the main program, which usually has a priority of C<0>. Note
402	that Coro::AnyEvent does I<not> run an event loop for you, so unless the
403	main program runs one, there will simply be no event loop to C<cede> to
404	(event handling will still work, somewhat inefficiently, but any thread
405	will have a higher priority than event handling in that case).
406
407	=item * provide a suitable idle callback.
408
409	In addition to hooking into C<ready>, this module will also provide a
410	C<$Coro::idle> handler that runs the event loop. It is best not to take
411	advantage of this too often, as this is rather inefficient, but it should
412	work perfectly fine.
413
414	=item * provide overrides for AnyEvent's condvars
415
416	This module installs overrides for AnyEvent's condvars. That is, when
417	the module is loaded it will provide its own condition variables. This
418	makes them coroutine-safe, i.e. you can safely block on them from within a
419	coroutine.
420
421	=item * lead to data corruption or worse
422
423	As C<unblock_sub> cannot be used by this module (as it is the module
424	that implements it, basically), you must not call into the event
425	loop recursively from any coroutine. This is not usually a difficult
426	restriction to live with, just use condvars, C<unblock_sub> or other means
427	of inter-coroutine-communications.
428
429	If you use a module that supports AnyEvent (or uses the same event loop
430	as AnyEvent, making the compatible), and it offers callbacks of any kind,
431	then you must not block in them, either (or use e.g. C<unblock_sub>), see
432	the description of C<unblock_sub> in the L<Coro> module.
433
434	This also means that you should load the module as early as possible,
435	as only condvars created after this module has been loaded will work
436	correctly.
437
438	=back
439
440	=head1 SEE ALSO
441
442	L<AnyEvent>, to see which event loops are supported, L<Coro::EV> and
443	L<Coro::Event> for more efficient and more correct solutions (they will be
444	used automatically if applicable).
445
446	=head1 AUTHOR
447
448	Marc Lehmann <schmorp@schmorp.de>
449	http://home.schmorp.de/
450
451	=cut
452