.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Thread 3pm"
.TH Thread 3pm "2018-08-22" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
POE::Component::Pool::Thread \- A POE Managed Boss/Worker threadpool.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use POE qw( Component::Pool::Thread );
\& 
\& POE::Component::Pool::Thread\->new
\&    ( MinFree       => 2,
\&      MaxFree       => 5,
\&      MaxThreads    => 15,
\&      StartThrneads => 5,
\&      Name          => "ThreadPool",
\&      EntryPoint    => \e&thread_entry_point,
\&      CallBack      => \e&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;
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is an expand-on-demand thread pool managed through a \s-1POE\s0 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.
.SH "RATIONALE"
.IX Header "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.
.PP
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\->\fIcreate()\fR method.
.PP
Communicating the results of a threads processing requires allowing it to exit.
This means you will require the overhead of threads\->\fIcreate()\fR 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.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new \s-1MANY THINGS\s0" 4
.IX Item "new MANY THINGS"
The new constructor is the only package method available with this package.  It
creates a \s-1POE\s0 thread pool session which you describe in the following
arguments.
.RS 4
.IP "EntryPoint \s-1CODE\s0" 4
.IX Item "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.
.IP "CallBack \s-1CODE\s0" 4
.IX Item "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).
.IP "Name \s-1ALIAS\s0" 4
.IX Item "Name ALIAS"
This argument descirbes the default alias your threadpool session is given.
.IP "StartThreads \s-1INTEGER\s0" 4
.IX Item "StartThreads INTEGER"
This argument describes the number of threads the component will create during
its \*(L"_start\*(R" state, or when the \s-1POE\s0 Session is being started.  This should be a
number greater than MinFree and less than or equal to MaxFree.
.IP "MaxThreads \s-1INTEGER\s0" 4
.IX Item "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 \s-1FIFO\s0 queue and assign them
threads as they complete their tasks.
.IP "MinFree \s-1INTEGER\s0" 4
.IX Item "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.
.IP "MaxFree \s-1INTEGER\s0" 4
.IX Item "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.
.RE
.RS 4
.RE
.SH "INLINE STATES"
.IX Header "INLINE STATES"
.IP "run \s-1LIST\s0" 4
.IX Item "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 \s-1FIFO\s0 if no threads are available and our
thread resources are exhausted.
.IP "shutdown" 4
.IX Item "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.
.SH "BUGS"
.IX Header "BUGS"
Oh I'm pretty sure of it.  If you find some, let me know.
.SH "THANKS"
.IX Header "THANKS"
Matt Cashner
.PP
Rocco Caputo
.SH "AUTHOR"
.IX Header "AUTHOR"
Scott McCoy (tag@cpan.org)