NAME

       POE::Component::Pool::Thread - A POE Managed Boss/Worker threadpool.

SYNOPSIS

        use POE qw( Component::Pool::Thread );

        POE::Component::Pool::Thread->new
           ( MinFree       => 2,
             MaxFree       => 5,
             MaxThreads    => 15,
             StartThrneads => 5,
             Name          => "ThreadPool",
             EntryPoint    => \&thread_entry_point,
             CallBack      => \&result_handler,
             inline_states => {
                 _start => sub {
                      my ($kernel, $heap) = @_[ KERNEL, HEAP ];

                      # We are inside the component session
                      $kernel->yield(run => @arguments);

                      $kernel->post(ThreadPool => run => @arguments);
                 },
             }
           );

        sub thread_entry_point {
           my (@arguments) = @_;

           return 1;
        }

        sub result_handler {
           my ($kernel, $result) = @_[ KERNEL, ARG0 ];

           $result == 1;
        }

DESCRIPTION

       This is an expand-on-demand thread pool managed through a POE session in a manner that
       does not interfer with cooperative multitasking.  A single pipe is created, each thread
       communicates its state to the main process through this pipe.  No serialization occurs
       (these are threads, not child processes), so execution is very fast.

RATIONALE

       Cooperative Co-routine type programming isn't always available.  Some third party software
       (dependent libraries and/or modules) and particular tasks block processing weither you
       like it or not.

       Creation of threads is a lot of overhead, infact quite a bit more overhead under the
       current implementation of ithreads than fork is.  Allocating these resources before you
       need them is an obvious solution to this problem, if you create the threads and re-use
       them, they're around when you need them without the horrendously slow threads->create()
       method.

       Communicating the results of a threads processing requires allowing it to exit.  This
       means you will require the overhead of threads->create() next time you need to accomplish
       this task.  With a thread pool designed in this fasion, the main thread itself has its own
       process loop.  The result of each iteration is passed through a thread safe queue,
       allowing you to collect the results of a threads execution without the thread exiting.

CONSTRUCTOR

       new MANY THINGS
           The new constructor is the only package method available with this package.  It
           creates a POE thread pool session which you describe in the following arguments.

           EntryPoint CODE
               This argument describes the entry point of the thread and is required.  In the
               actual implementation, this is not actually an entry point.  This is instead a
               coderef the thread will call repeatedly.  The arguments of this subroutine will be
               the arguments received by the controlling session.  In order to pass references as
               arguments, each reference must be shared (threads::shared).  Filehandles and
               blessed references cannot be shared.  You will have to translate them yourself.
               With file handles, you can pass simply the file descriptor and reopen it in the
               child thread.  With blessed references, you can pass the datastructure only, and
               rebless the reference in the thread.

           CallBack CODE
               This argument descirbes the result handler, which is where the captured results of
               a threads last execution are sent.  As with EntryPoint subroutine arguments, any
               data structures you wish to pass through return results must be explicitly shared
               (threads::shared).

           Name ALIAS
               This argument descirbes the default alias your threadpool session is given.

           StartThreads INTEGER
               This argument describes the number of threads the component will create during its
               "_start" state, or when the POE Session is being started.  This should be a number
               greater than MinFree and less than or equal to MaxFree.

           MaxThreads INTEGER
               This argument descirbes the maximum number of threads this component will create
               for this task.  If the component is assigned more tasks than threads, it will
               place the remaining tasks in an internal FIFO queue and assign them threads as
               they complete their tasks.

           MinFree INTEGER
               This argument sets the minimum number of free threads to maintain.  When the
               component is assigned a new task, if there are less than this number of threads
               available, it will yield a request to create a new thread at the components
               convience.

           MaxFree INTEGER
               This argument provides the maximum number of free threads to maintain.  Upon
               completion of a task, this value is checked.  If there are more free threads than
               this value available, the oldest thread is asked to shut down.

INLINE STATES

       run LIST
           The run state assigns a task to one of the free threads in the pool, or appends the
           task to the components internal FIFO if no threads are available and our thread
           resources are exhausted.

       shutdown
           This state politely asks all threads to exit, deletes the wheel watching the one way
           pipe threads are using to communicate, removes the session alias and awaits a clean
           session shutdown.

BUGS

       Oh I'm pretty sure of it.  If you find some, let me know.

THANKS

       Matt Cashner

       Rocco Caputo

AUTHOR

       Scott McCoy (tag@cpan.org)