Provided by: tcl-thread_2.8.2-1_amd64 bug

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  threadpool  instance.
                     During  threadpool  creation,  the  implementation 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 command and posting jobs to the job queue.

              -maxworkers number
                     Maximum number of worker threads allowed for this threadpool 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
                     available  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 threadpool instance will allow maximum of 4 worker threads running
                     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 commands, 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 contain
                     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 available, 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 creation, 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 commands 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 initialize.

       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 threadpool 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
              cancelled.   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 reference 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  workers dynamically as the pool processing is suspended.
              Number of workers is maintained to the count that was found prior suspending 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 significant; 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 tuning 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, tsv, ttrace

KEYWORDS

       thread, threadpool