=head1 NAME

Coro::Multicore - make coro threads on multiple cores with specially supported modules

=head1 SYNOPSIS

 use Coro::Multicore;

=head1 DESCRIPTION

While L<Coro> threads (unlike ithreads) provide real threads similar to
pthreads, python threads and so on, they do not run in parallel to each
other even on machines with multiple CPUs or multiple CPU cores.

This module lifts this restriction under two very specific but useful
conditions: firstly, the coro thread executes in XS code and does not
touch any perl data structures, and secondly, the XS code is specially
prepared to allow this.

This means that, when you call an XS function of a module prepared for it,
this XS function can execute in parallel to any other Coro threads.

The mechanism to support this is easily added to existing modules
and is independent of L<Coro> or L<Coro::Multicore>, and therefore
could be used, without changes, with other, similar, modules, or even
the perl core, should it gain real thread support anytime soon. See
L<http://pod.tst.eu/http://cvs.schmorp.de/Coro-Multicore/perlmulticore.h>
for more info on how to prepare a module to allow parallel execution.

This module is an L<AnyEvent> user (and also, if not obvious, uses
L<Coro>).

=head1 HOW TO USE IT

It could hardly be simpler - if you use coro threads, and before you call
a supported lengthy operation implemented in XS, use this module and other
coro threads can run in parallel:

   use Coro::Multicore;

This module has no important API functions to learn or remember. All you
need to do is I<load> it before you can take advantage of it.

=head1 API FUNCTION

There is currently a lone API function documented for this module:

=over 4

=item $previous = Coro::Multicore::max_idle_threads [$count]

To run on multiple cores, this module creates I<threads>. Since thread
creation is costly, it will keep some of them around for future uses. This
function returns the current maximum number of threads that are being kept
around (default: C<8>), and can be used to set a new limit, in case you
have bigger requirements.

Future implementations will also provide a timeout mechanism, for even
better behaviour.

=back

=cut

package Coro::Multicore;

use Coro ();
use AnyEvent ();

BEGIN {
   our $VERSION = 0.02;

   use XSLoader;
   XSLoader::load __PACKAGE__, $VERSION;
}

our $WATCHER = AE::io fd, 0, \&poll;

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://software.schmorp.de/pkg/AnyEvent-XSThreadPool.html

=cut

1