manpagez: man pages & more
man tpool(n)
Home | html | info | man
tpool(n)                                                              tpool(n)



______________________________________________________________________________


NAME

       tpool  -  Part  of  the  Tcl  threading extension implementing pools of
       worker threads.


SYNOPSIS

       package require Tcl  8.4

       package require Thread  ?2.8?

       tpool::create ?options?

       tpool::names

       tpool::post ?-detached? ?-nowait? tpool script

       tpool::wait tpool joblist ?varname?

       tpool::cancel tpool joblist ?varname?

       tpool::get tpool job

       tpool::preserve tpool

       tpool::release tpool

       tpool::suspend tpool

       tpool::resume tpool

______________________________________________________________________________


DESCRIPTION

       This package creates and manages pools of worker threads. It allows you
       to  post  jobs  to  worker  threads  and wait for their completion. The
       threadpool implementation is Tcl event-loop aware. That means that  any
       time  a caller is forced to wait for an event (job being completed or a
       worker thread becoming idle or initialized),  the  implementation  will
       enter  the  event loop and allow for servicing of other pending file or
       timer (or any other supported) events.


COMMANDS

       tpool::create ?options?
              This command creates new threadpool. It accepts several  options
              as  key-value  pairs.  Options  are used to tune some threadpool
              parameters.  The command returns the ID  of  the  newly  created
              threadpool.

              Following options are supported:

              -minworkers number
                     Minimum  number of worker threads needed for this thread-
                     pool instance.  During threadpool creation, the implemen-
                     tation will create somany worker threads upfront and will
                     keep at least number of them alive during the lifetime of
                     the threadpool instance.  Default value of this parameter
                     is 0 (zero). which means that  a  newly  threadpool  will
                     have  no worker threads initialy. All worker threads will
                     be started on demand by callers running tpool::post  com-
                     mand and posting jobs to the job queue.

              -maxworkers number
                     Maximum number of worker threads allowed for this thread-
                     pool instance.  If a new job is pending and there are  no
                     idle  worker  threads  available, the implementation will
                     try to create new worker thread. If the number of  avail-
                     able  worker  threads is lower than the given number, new
                     worker thread will start. The caller  will  automatically
                     enter the event loop and wait until the worker thread has
                     initialized. If. however, the number of available  worker
                     threads  is  equal  to  the given number, the caller will
                     enter the event loop and wait for the first worker thread
                     to get idle, thus ready to run the job.  Default value of
                     this parameter is 4 (four), which means that the  thread-
                     pool instance will allow maximum of 4 worker threads run-
                     ning jobs or being idle  waiting  for  new  jobs  to  get
                     posted to the job queue.

              -idletime seconds
                     Time  in  seconds an idle worker thread waits for the job
                     to get posted to the job queue. If no job arrives  during
                     this  interval  and  the  time expires, the worker thread
                     will check  the  number  of  currently  available  worker
                     threads  and  if the number is higher than the number set
                     by the minthreads option, it will exit.  If an exitscript
                     has  been  defined,  the exiting worker thread will first
                     run the script  and  then  exit.  Errors  from  the  exit
                     script, if any, are ignored.

                     The  idle  worker thread is not servicing the event loop.
                     If you, however, put the worker  thread  into  the  event
                     loop,  by  evaluating the vwait or other related Tcl com-
                     mands, the worker thread will not be in the  idle  state,
                     hence  the  idle  timer  will  not be taken into account.
                     Default value for this option is unspecified.

              -initcmd script
                     Sets a Tcl script used to initialize new  worker  thread.
                     This is usually used to load packages and commands in the
                     worker, set default  variables,  create  namespaces,  and
                     such.  If  the  passed  script runs into a Tcl error, the
                     worker will not be created  and  the  initiating  command
                     (either  the  tpool::create  or  tpool::post)  will throw
                     error.  Default value for  this  option  is  unspecified,
                     hence, the Tcl interpreter of the worker thread will con-
                     tain just the initial set of Tcl commands.

              -exitcmd script
                     Sets a Tcl script run when the idle worker thread  exits.
                     This  is  normaly used to cleanup the state of the worker
                     thread, release reserved resources,  cleanup  memory  and
                     such.  Default value for this option is unspecified, thus
                     no Tcl script will run on the worker thread exit.


       tpool::names
              This command returns a list of IDs of threadpools  created  with
              the  tpool::create  command.  If  no threadpools were found, the
              command will return empty list.

       tpool::post ?-detached? ?-nowait? tpool script
              This command sends a script to the target tpool  threadpool  for
              execution.  The  script  will be executed in the first available
              idle worker thread. If there are no idle worker  threads  avail-
              able,  the command will create new one, enter the event loop and
              service events until the newly created thread is initialized. If
              the  current  number  of  worker threads is equal to the maximum
              number of worker threads, as defined during the threadpool  cre-
              ation,  the command will enter the event loop and service events
              while waiting for one of the worker threads to become idle.   If
              the  optional  ?-nowait? argument is given, the command will not
              wait for one idle worker. It will just  place  the  job  in  the
              pool's job queue and return immediately.

              The  command  returns  the ID of the posted job. This ID is used
              for subsequent tpool::wait, tpool::get  and  tpool::cancel  com-
              mands  to  wait for and retrieve result of the posted script, or
              cancel the posted job respectively. If the optional  ?-detached?
              argument  is  specified, the command will post a detached job. A
              detached job can not be cancelled or  waited  upon  and  is  not
              identified by the job ID.

              If  the  threadpool  tpool  is  not  found in the list of active
              thread pools, the command will throw error. The error will  also
              be  triggered  if  the newly created worker thread fails to ini-
              tialize.

       tpool::wait tpool joblist ?varname?
              This command waits for one or many jobs, whose job IDs are given
              in the joblist to get processed by the worker thread(s). If none
              of the specified jobs are ready,  the  command  will  enter  the
              event  loop,  service  events  and wait for the first job to get
              ready.

              The command returns the  list  of  completed  job  IDs.  If  the
              optional variable ?varname? is given, it will be set to the list
              of jobs in the joblist which are still pending. If  the  thread-
              pool  tpool is not found in the list of active thread pools, the
              command will throw error.

       tpool::cancel tpool joblist ?varname?
              This command cancels the previously posted  jobs  given  by  the
              joblist  to  the  pool tpool. Job cancellation succeeds only for
              job still waiting to be processed. If the job is  already  being
              executed  by one of the worker threads, the job will not be can-
              celled.  The command returns the list of cancelled job  IDs.  If
              the  optional variable ?varname? is given, it will be set to the
              list of jobs in the joblist which were  not  cancelled.  If  the
              threadpool  tpool  is  not  found  in  the list of active thread
              pools, the command will throw error.

       tpool::get tpool job
              This command retrieves the result of the previously posted  job.
              Only  results  of  jobs waited upon with the tpool::wait command
              can be retrieved. If the execution of  the  script  resulted  in
              error, the command will throw the error and update the errorInfo
              and errorCode variables correspondingly. If the  pool  tpool  is
              not  found  in  the  list of threadpools, the command will throw
              error.  If the job job is not ready for retrieval, because it is
              currently  being executed by the worker thread, the command will
              throw error.

       tpool::preserve tpool
              Each call to this command increments the  reference  counter  of
              the  threadpool  tpool  by one (1). Command returns the value of
              the reference counter after the increment.  By incrementing  the
              reference  counter,  the caller signalizes that he/she wishes to
              use the resource for a longer period of time.

       tpool::release tpool
              Each call to this command decrements the  reference  counter  of
              the threadpool tpool by one (1).Command returns the value of the
              reference counter  after  the  decrement.   When  the  reference
              counter  reaches  zero  (0),  the threadpool tpool is marked for
              termination. You should not reference the threadpool  after  the
              tpool::release  command  returns zero. The tpool handle goes out
              of scope and should not be used any more. Any  following  refer-
              ence to the same threadpool handle will result in Tcl error.

       tpool::suspend tpool
              Suspends  processing  work  on  this queue. All pool workers are
              paused but additional work can be added to the pool.  Note  that
              adding the additional work will not increase the number of work-
              ers dynamically as the pool processing is suspended.  Number  of
              workers is maintained to the count that was found prior suspend-
              ing worker activity.  If you need to assure  certain  number  of
              worker  threads,  use the minworkers option of the tpool::create
              command.

       tpool::resume tpool
              Resume processing work on this  queue.  All  paused  (suspended)
              workers  are  free to get work from the pool. Note that resuming
              pool operation will just let already created workers to proceed.
              It  will not create additional worker threads to handle the work
              posted to the pool's work queue.



DISCUSSION

       Threadpool is one of the most common threading paradigm when  it  comes
       to  server  applications  handling  a  large number of relatively small
       tasks.  A very simplistic model for building a server application would
       be  to  create a new thread each time a request arrives and service the
       request in the new thread. One of the disadvantages of this approach is
       that the overhead of creating a new thread for each request is signifi-
       cant; a server that created a new thread for each request  would  spend
       more  time and consume more system resources in creating and destroying
       threads than in processing actual user requests.  In  addition  to  the
       overhead  of  creating  and  destroying threads, active threads consume
       system resources.  Creating too many threads can cause  the  system  to
       run out of memory or trash due to excessive memory consumption.

       A  thread  pool  offers  a solution to both the problem of thread life-
       cycle overhead and the problem of resource trashing. By reusing threads
       for  multiple  tasks,  the thread-creation overhead is spread over many
       tasks.  As a bonus, because the thread already exists  when  a  request
       arrives,  the  delay introduced by thread creation is eliminated. Thus,
       the request can be serviced immediately. Furthermore, by properly  tun-
       ing  the  number  of threads in the thread pool, resource thrashing may
       also be eliminated by forcing any request to wait  until  a  thread  is
       available to process it.


SEE ALSO

       thread(n), tsv(n), ttrace(n)


KEYWORDS

       thread, threadpool



Tcl Threading                         2.8                             tpool(n)

tcl 8.6.6 - Generated Mon Aug 22 18:23:09 CDT 2016
© manpagez.com 2000-2017
Individual documents may contain additional copyright information.