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)

perl v5.26.2                                       2018-08-22                                        Thread(3pm)