=head1 NAME

AnyEvent::XSThreadPool - manage xs-level thread pools to do stuff asynchronously

=head1 SYNOPSIS

 use AnyEvent::XSThreadPool;

=head1 DESCRIPTION

=over 4

=cut

package AnyEvent::XSThreadPool;

BEGIN {
   our $VERSION = 0.02;

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

use AnyEvent;

=item $pool = new AnyEvent::XSThreadPool

=cut

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

   my $self = bless [""], $class;

   my $poll_cb = _init $self->[0];
   $self->[1] = AE::io $self->fileno, 0, $poll_cb;

   $self
}

sub DESTROY {
   &_destroy;
}

=item $pool->req (REQUEST_TYPE, [request-args], $callback)

=item AnyEvent::XSThreadPool::req $pool, REQUEST_TYPE, [request-args], $callback

This is the same as the C<< ->req >> method, above, except as a function
call. If you submit many small requests, the function syntax executes much
faster, but is less convenient than the method syntax.

=item $fd = $pool->fileno

=item $nreqs = $pool->nreqs

=item $nready = $pool->nready

=item $npending = $pool->npending

=item $threadcount = $pool->nthreads

=item $pool->max_poll_time ($seconds)

=item $pool->max_poll_reqs ($maxreqs)

=item $pool->idle_timeout ($seconds)

=item $pool->max_idle ($threads)

=item $pool->min_parallel ($nthreads)

=item $pool->max_parallel ($nthreads)

=back

=head2 AnyEvent::XSThreadPool REQUEST TYPES DEFINED BY THIS MODULE

This module defines only two rather lame request types, which can nevertheless be used to
test out the module.

=over 4

=item AnyEvent::XSThreadPool::sleep $seconds, $callback->()

This request type simply puts the worker thread to sleep for the given
number of (fractional) seconds. This can be used to simulate a very slow
request, without actually putting stress on the machine.

Example: execute two 1.2 second sleeps and wait for them. Normally this
should take only about 1.2 seconds overall, as the sleeps execute in
parallel.

   AnyEvent::XSThreadPool::cpupool->req (AnyEvent::XSThreadPool::sleep, 1.2, my $cv1 = AE::cv);
   AnyEvent::XSThreadPool::cpupool->req (AnyEvent::XSThreadPool::sleep, 1.2, my $cv2 = AE::cv);
   $cv1->recv;
   $cv2->recv;

=item AnyEvent::XSThreadPool::burn $seconds, $callback->($iterations)

This request type burns cpu cycles by calling C<gettimeofday> (or an
equivalent function) in a loop, for the given number of (fractional)
seconds, counting how many times it looped.

This can be used to simulate actual cpu load on your machine, or it could
be used as a primitive benchmark (although this is not advised).

Example: see how often the module can call gettimeofday within 0.1 seconds.

   my $cv = AE::cv;
   AnyEvent::XSThreadPool::cpupool->req (AnyEvent::XSThreadPool::burn => 0.1, sub {
      printf "executed %d cycles in 0.1s\n", $_[0];
      $cv->();
   });
   $cv->recv;

   # outputs, on my current development box:
   # executed 3900480 cycles in 0.1s

=back

=head1 AUTHOR

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

=cut

1