Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 pa-
	      rameters.	 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 en-
		     ter 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.  De-
		     fault 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 er-
		     ror.  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  op-
	      tional  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 er-
	      ror,  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 er-
	      ror.  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-cy-
       cle 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, tsv, ttrace

KEYWORDS
       thread, threadpool

Tcl Threading			      2.8			      tpool(n)

NAME | SYNOPSIS | DESCRIPTION | COMMANDS | DISCUSSION | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tpool&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help