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)