Scroll to navigation

Thread(3pm) User Contributed Perl Documentation Thread(3pm)

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

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.
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.
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).
This argument descirbes the default alias your threadpool session is given.
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.
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.
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.
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

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.
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)

2018-08-22 perl v5.26.2