thread man page on OpenMandriva

Man page or keyword search:  
man Server   8135 pages
apropos Keyword Search (all sections)
Output format
OpenMandriva logo
[printable version]


thread(n)							     thread(n)

______________________________________________________________________________

NAME
       thread - Extension for script access to Tcl threading

SYNOPSIS
       package require Tcl  8.4

       package require Thread  ?2.7?

       thread::create ?-joinable? ?-preserved? ?script?

       thread::preserve ?id?

       thread::release ?-wait? ?id?

       thread::id

       thread::errorproc ?procname?

       thread::unwind

       thread::exit

       thread::names

       thread::exists id

       thread::send ?-async? ?-head? id script ?varname?

       thread::broadcast id script

       thread::wait

       thread::eval ?-lock mutex? arg ?arg ...?

       thread::join id

       thread::configure id ?option? ?value? ?...?

       thread::transfer id channel

       thread::detach channel

       thread::attach channel

       thread::mutex

       thread::mutex create ?-recursive?

       thread::mutex destroy mutex

       thread::mutex lock mutex

       thread::mutex unlock mutex

       thread::rwmutex

       thread::rwmutex create

       thread::rwmutex destroy mutex

       thread::rwmutex rlock mutex

       thread::rwmutex wlock mutex

       thread::rwmutex unlock mutex

       thread::cond

       thread::cond create

       thread::cond destroy cond

       thread::cond notify cond

       thread::cond wait cond mutex ?ms?

_________________________________________________________________

DESCRIPTION
       The thread extension creates threads that contain Tcl interpreters, and
       it lets you send scripts to those threads for evaluation.  Additionaly,
       it  provides script-level access to basic thread synchronization primi‐
       tives, like mutexes and condition variables.

COMMANDS
       This section describes commands for creating and destroying threads and
       sending scripts to threads for evaluation.

       thread::create ?-joinable? ?-preserved? ?script?
	      This  command  creates a thread that contains a Tcl interpreter.
	      The Tcl interpreter either evaluates  the	 optional  script,  if
	      specified, or it waits in the event loop for scripts that arrive
	      via the  thread::send  command.  The  result,  if	 any,  of  the
	      optional	script is never returned to the caller.	 The result of
	      thread::create is the ID of the thread. This is the opaque  han‐
	      dle  which  identifies  the  newly  created thread for all other
	      package commands. The handle of the thread  goes	out  of	 scope
	      automatically   when   thread   is  marked  for  exit  (see  the
	      thread::release command below).

	      If the optional script argument contains the  thread::wait  com‐
	      mand  the thread will enter into the event loop. If such command
	      is not found  in the script the thread will run  the  script  to
	      the end and exit. In that case, the handle may be safely ignored
	      since it refers to a thread which does not exists	 any  more  at
	      the time when the command returns.

	      Using flag -joinable it is possible to create a joinable thread,
	      i.e.  one	 upon  whose  exit  can	 be  waited  upon   by	 using
	      thread::join  command.   Note that failure to join a thread cre‐
	      ated with -joinable flag results in resource and memory leaks.

	      Threads created by the thread::create cannot be destroyed force‐
	      fully.  Consequently,  there  is no corresponding thread destroy
	      command. A thread may only be released using the thread::release
	      and if its internal reference count drops to zero, the thread is
	      marked for exit. This kicks the thread out  of  the  event  loop
	      servicing and the thread continues to execute commands passed in
	      the script argument, following the thread::wait command. If this
	      was  the	last  command  in  the script, as usualy the case, the
	      thread will exit.

	      It is possible to create a situation in which it may be impossi‐
	      ble to terminate the thread, for example by putting some endless
	      loop after the thread::wait or entering the event loop again  by
	      doing  an	 vwait-type  of command. In such cases, the thread may
	      never exit. This is considered to be a bad practice  and	should
	      be  avoided if possible. This is best illustrated by the example
	      below:
		  # You should never do ...
		  set tid [thread::create {
		      package require Http
		      thread::wait
		      vwait forever ; # <-- this!
		  }]
	      The thread created in the above example will never  be  able  to
	      exit.   After  it	 has  been  released  with  the	 last matching
	      thread::release  call,  the  thread  will	 jump	out   of   the
	      thread::wait and continue to execute commands following. It will
	      enter vwait command and wait endlessly for events. There	is  no
	      way  one	can  terminate such thread, so you wouldn't want to do
	      this!

	      Each newly created has its internal reference counter set	 to  0
	      (zero),  i.e. it is unreserved. This counter gets incremented by
	      a	 call  to  thread::preserve  and  decremented  by  a  call  to
	      thread::release command. These two commands implement simple but
	      effective thread reservation system and  offer  predictable  and
	      controllable thread termination capabilities. It is however pos‐
	      sible to create initialy preserved threads by using  flag	 -pre‐
	      served  of the thread::create command. Threads created with this
	      flag have the initial value of the reference counter of 1 (one),
	      and are thus initially marked reserved.

       thread::preserve ?id?
	      This  command increments the thread reference counter. Each call
	      to this command increments the reference	counter	 by  one  (1).
	      Command  returns	the  value  of the reference counter after the
	      increment.  If called with the optional thread id,  the  command
	      preserves the given thread. Otherwise the current thread is pre‐
	      served.

	      With reference counting, one can implement controlled access  to
	      a	 shared Tcl thread. By incrementing the reference counter, the
	      caller signalizes that he/she wishes to use  the	thread	for  a
	      longer  period of time. By decrementing the counter, caller sig‐
	      nalizes that he/she has finished using the thread.

       thread::release ?-wait? ?id?
	      This command decrements the thread reference counter. Each  call
	      to this command decrements the reference counter by one (1).  If
	      called with the optional thread id,  the	command	 releases  the
	      given  thread.  Otherwise, the current thread is released.  Com‐
	      mand returns the value of the reference counter after the decre‐
	      ment.   When  the reference counter reaches zero (0), the target
	      thread is marked for termination. You should not	reference  the
	      thread  after  the thread::release command returns zero or nega‐
	      tive integer.  The handle of the thread goes out	of  scope  and
	      should not be used any more. Any following reference to the same
	      thread handle will result in Tcl error.

	      Optional flag -wait instructs the caller thread to wait for  the
	      target thread to exit, if the effect of the command would result
	      in termination of the target thread, i.e. if the	return	result
	      would  be zero (0). Without the flag, the caller thread does not
	      wait for the target thread to exit.  Care	 must  be  taken  when
	      using  the -wait, since this may block the caller thread indefi‐
	      nitely.  This option has been implemented for some special  uses
	      of  the  extension  and  is  deprecated for regular use. Regular
	      users should create joinable  threads  by	 using	the  -joinable
	      option  of  the  thread::create  command and the thread::join to
	      wait for thread to exit.

       thread::id
	      This command returns the ID of the current thread.

       thread::errorproc ?procname?
	      This command sets a handler for errors  that  occur  in  scripts
	      sent  asynchronously,  using the -async flag of the thread::send
	      command, to other threads. If no handler is specified, the  cur‐
	      rent handler is returned. The empty string resets the handler to
	      default (unspecified) value.  An	uncaught  error	 in  a	thread
	      causes  an  error message to be sent to the standard error chan‐
	      nel. This default reporting scheme can be changed by registering
	      a procedure which is called to report the error. The procname is
	      called in the interpreter	 that  invoked	the  thread::errorproc
	      command. The procname is called like this:
		  myerrorproc thread_id errorInfo

       thread::unwind
	      Use  of  this  command  is deprecated in favour of more advanced
	      thread reservation system implemented with thread::preserve  and
	      thread::release  commands.  Support  for	thread::unwind command
	      will dissapear in some future major release of the extension.

	      This command stops a prior thread::wait  command.	 Execution  of
	      the script passed to newly created thread will continue from the
	      thread::wait command. If thread::wait was the  last  command  in
	      the  script,  the	 thread	 will  exit. The command returns empty
	      result but may trigger Tcl error with the message "target thread
	      died" in some situations.

       thread::exit
	      Use  of  this  command  is deprecated in favour of more advanced
	      thread reservation system implemented with thread::preserve  and
	      thread::release  commands. Support for thread::exit command will
	      dissapear in some future major release of the extension.

	      This command forces a thread stuck in the	 thread::wait  command
	      to unconditionaly exit. The execution of thread::exit command is
	      guaranteed to leave  the	program	 memory	 in  the  unconsistent
	      state,  produce  memory  leaks  and  otherwise affect other sub‐
	      sytem(s) of the Tcl application in an unpredictable manner.  The
	      command  returns empty result but may trigger Tcl error with the
	      message "target thread died" in some situations.

       thread::names
	      This command returns a list of thread IDs. These	are  only  for
	      threads  that  have been created via thread::create command.  If
	      your application creates other threads at the C level, they  are
	      not reported by this command.

       thread::exists id
	      Returns  true  (1)  if  thread given by the id parameter exists,
	      false (0) otherwise. This applies only  for  threads  that  have
	      been created via thread::create command.

       thread::send ?-async? ?-head? id script ?varname?
	      This  command passes a script to another thread and, optionally,
	      waits for the result. If the -async flag is specified, the  com‐
	      mand  does  not wait for the result and it returns empty string.
	      The target thread must enter it's event loop in order to receive
	      scripts  sent  via  this	command.  This	is done by default for
	      threads created without a startup script. Threads can enter  the
	      event loop explicitly by calling thread::wait or any other rele‐
	      vant Tcl/Tk command, like update, vwait, etc.

	      Optional varname specifies name of the  variable	to  store  the
	      result  of  the  script.	Without	 the  -async flag, the command
	      returns the evaluation code,  similarily	to  the	 standard  Tcl
	      catch  command.  If,  however, the -async flag is specified, the
	      command returns immediately and caller can later vwait on	 ?var‐
	      name? to get the result of the passed script
		  set t1 [thread::create]
		  set t2 [thread::create]
		  thread::send -async $t1 "set a 1" result
		  thread::send -async $t2 "set b 2" result
		  for {set i 0} {$i < 2} {incr i} {
		      vwait result
		  }
	      In the above example, two threads were fed work and both of them
	      were instructed to signalize the same variable "result"  in  the
	      calling  thread.	The caller entered the event loop twice to get
	      both results. Note, however, that	 the  order  of	 the  received
	      results  may vary, depending on the current system load, type of
	      work done, etc, etc.

	      Many threads can	simultaneously	send  scripts  to  the	target
	      thread  for  execution.  All  of them are entered into the event
	      queue of the target thread  and  executed	 on  the  FIFO	basis,
	      intermingled  with  optional  other  events pending in the event
	      queue of the target thread.  Using the optional ?-head?  switch,
	      scripts  posted to the thread's event queue can be placed on the
	      head, instead on the tail of the queue, thus being  executed  in
	      the LIFO fashion.

       thread::broadcast id script
	      This command passes a script to all threads created by the pack‐
	      age for execution. It does not wait for response from any of the
	      threads.

       thread::wait
	      This enters the event loop so a thread can receive messages from
	      the thread::send command.	 This  command	should	only  be  used
	      within the script passed to the thread::create. It should be the
	      very last command in the script. If this is not  the  case,  the
	      exiting thread will continue executing the script lines pass the
	      thread::wait which is usually not what you want and/or expect.
		  set t1 [thread::create {
		      #
		      # Do some initialization work here
		      #
		      thread::wait ; # Enter the event loop
		  }]

       thread::eval ?-lock mutex? arg ?arg ...?
	      This command concatenates passed	arguments  and	evaluates  the
	      resulting	 script	 under	the  mutex  protection. If no mutex is
	      specified by using the  ?-lock  mutex?  optional	argument,  the
	      internal static mutex is used.

       thread::join id
	      This  command  waits  for the thread with ID id to exit and then
	      returns it's exit code. Errors  will  be	returned  for  threads
	      which are not joinable or already waited upon by another thread.
	      Upon the join the handle of the thread has gone out of scope and
	      should not be used any more.

       thread::configure id ?option? ?value? ?...?
	      This  command configures various low-level aspects of the thread
	      with ID id in the similar way as the standard Tcl command	 fcon‐
	      figure  configures  some	Tcl channel options. Options currently
	      supported are: -eventmark and -unwindonerror.

	      The -eventmark option, when set,	limits	the  number  of	 asyn‐
	      chronously  posted  scripts  to  the  thread  event  loop.   The
	      thread::send -async command will block until the number of pend‐
	      ing scripts in the event loop does not drop below the value con‐
	      figured with -eventmark. Default value for the -eventmark	 is  0
	      (zero)  which effectively disables the checking, i.e. allows for
	      unlimited number of posted scripts.

	      The -unwindonerror option, when set, causes the target thread to
	      unwind if the result of the script processing resulted in error.
	      Default value for the -unwindonerror is 0 (false),  i.e.	thread
	      continues	 to  process  scripts  after one of the posted scripts
	      fails.

       thread::transfer id channel
	      This moves the specified channel from  the  current  thread  and
	      interpreter to the main interpreter of the thread with the given
	      id. After the move the current interpreter has no access to  the
	      channel  any more, but the main interpreter of the target thread
	      will be able to use it from now on.  The command waits until the
	      other thread has incorporated the channel. Because of this it is
	      possible to deadlock the participating threads by commanding the
	      other  through  a synchronous thread::send to transfer a channel
	      to us.  This easily extends into longer loops of threads waiting
	      for each other. Other restrictions: the channel in question must
	      not be shared among multiple interpreters running in the sending
	      thread.  This  automatically  excludes  the special channels for
	      standard input, output and error.

	      Due to the internal Tcl core implementation and the  restriction
	      on  transferring shared channels, one has to take extra measures
	      when transferring socket channels created by accepting the  con‐
	      nection out of the socket commands callback procedures:
		  socket -server _Accept 2200
		  proc _Accept {s ipaddr port} {
		      after idle [list Accept $s $ipaddr $port]
		  }
		  proc Accept {s ipaddr port} {
		      set tid [thread::create]
		      thread::transfer $tid $s
		  }

       thread::detach channel
	      This  detaches the specified channel from the current thread and
	      interpreter. After that, the current interpreter has  no	access
	      to  the  channel	any  more.  The channel is in the parked state
	      until some other (or the same) thread attaches the channel again
	      with  thread::attach.   Restrictions:  same  as for transferring
	      shared channels with the thread::transfer command.

       thread::attach channel
	      This attaches the previously detached  channel  in  the  current
	      thread/interpreter.  For	already existing channels, the command
	      does nothing, i.e. it is not an error to attach the same channel
	      more  than  once.	 The  first operation will actualy perform the
	      operation, while all subsequent operation will just do  nothing.
	      Command  throws error if the channel cannot be found in the list
	      of detached channels and/or in the current interpreter.

       thread::mutex
	      Mutexes are most common thread synchronization primitives.  They
	      are  used	 to synchronize access from two or more threads to one
	      or more shared resources.	 This  command	provides  script-level
	      access  to exclusive and/or recursive mutexes. Exclusive mutexes
	      can be locked only once by one thread, while  recursive  mutexes
	      can  be  locked  many  times  by	the same thread. For recursive
	      mutexes, number of lock and unlock operations must match, other‐
	      wise, the mutex will never be released, which would lead to var‐
	      ious deadlock situations.

	      Care has to be taken when using  mutexes	in  an	multithreading
	      program.	 Improper  use of mutexes may lead to various deadlock
	      situations, especially when using exclusive mutexes.

	      The thread::mutex command	 supports  following  subcommands  and
	      options:

	      thread::mutex create ?-recursive?
		     Creates  the  mutex  and returns it's opaque handle. This
		     handle should be used for any  future  reference  to  the
		     newly  created  mutex.  If no optional ?-recursive? argu‐
		     ment was specified, the  command  creates	the  exclusive
		     mutex.  With  the ?-recursive? argument, the command cre‐
		     ates a recursive mutex.

	      thread::mutex destroy mutex
		     Destroys the mutex. Mutex should  be  in  unlocked	 state
		     before  the  destroy attempt. If the mutex is locked, the
		     command will throw Tcl error.

	      thread::mutex lock mutex
		     Locks the mutex. Locking the exclusive  mutex  may	 throw
		     Tcl error if on attempt to lock the same mutex twice from
		     the same thread. If your program logic forces you to lock
		     the  same	mutex twice or more from the same thread (this
		     may happen in recursive procedure invocations) you should
		     consider using the recursive mutexes.

	      thread::mutex unlock mutex
		     Unlocks the mutex so some other thread may lock it again.
		     Attempt to unlock the already unlocked mutex  will	 throw
		     Tcl error.

       thread::rwmutex
	      This   command   creates	 many-readers/single-writer   mutexes.
	      Reader/writer mutexes allow you to serialize access to a	shared
	      resource	more optimally.	 In situations where a shared resource
	      gets mostly read and seldom modified, you might gain  some  per‐
	      formace  by  using reader/writer mutexes instead of exclusive or
	      recursive mutexes.

	      For reading the resource, thread should obtain a	read  lock  on
	      the  resource.   Read  lock  is non-exclusive, meaning that more
	      than one thread can obtain a read lock  to  the  same  resource,
	      without  waiting	on  other readers.  For changing the resource,
	      however, a thread must obtain a exclusive write lock. This  lock
	      effectively  blocks all threads from gaining the read-lock while
	      the resource is been modified by the writer thread.  Only	 after
	      the  write  lock	has  been  released, the resource may be read-
	      locked again.

	      The thread::rwmutex command supports following  subcommands  and
	      options:

	      thread::rwmutex create
		     Creates  the  reader/writer mutex and returns it's opaque
		     handle.  This handle should be used for any future refer‐
		     ence to the newly created mutex.

	      thread::rwmutex destroy mutex
		     Destroys the reader/writer mutex. If the mutex is already
		     locked, attempt to destroy it will throw Tcl error.

	      thread::rwmutex rlock mutex
		     Locks the mutex for reading. More	than  one  thread  may
		     read-lock the same mutex at the same time.

	      thread::rwmutex wlock mutex
		     Locks  the	 mutex for writing. Only one thread may write-
		     lock the same mutex at the same time. Attempt  to	write-
		     lock same mutex twice from the same thread will throw Tcl
		     error.

	      thread::rwmutex unlock mutex
		     Unlocks the mutex so some other thread may lock it again.
		     Attempt  to  unlock already unlocked mutex will throw Tcl
		     error.

       thread::cond
	      This command provides script-level  access  to  condition	 vari‐
	      ables.   A condition variable creates a safe environment for the
	      program to test some condition, sleep on it when	false  and  be
	      awakened when it might have become true. A condition variable is
	      always used in the conjuction with an exclusive  mutex.  If  you
	      attempt to use other type of mutex in conjuction with the condi‐
	      tion variable, a Tcl error will be thrown.

	      The command supports following subcommands and options:

	      thread::cond create
		     Creates the condition variable and	 returns  it's	opaque
		     handle.  This handle should be used for any future refer‐
		     ence to newly created condition variable.

	      thread::cond destroy cond
		     Destroys condition variable cond. Extreme care has to  be
		     taken  that  nobody is using (i.e. waiting on) the condi‐
		     tion variable, otherwise unexpected errors may happen.

	      thread::cond notify cond
		     Wakes up all threads waiting on  the  condition  variable
		     cond.

	      thread::cond wait cond mutex ?ms?
		     This  command  is used to suspend program execution until
		     the condition variable cond has  been  signalled  or  the
		     optional  timer has expired.  The exclusive mutex must be
		     locked by the calling thread on entrance to this command.
		     If	 the  mutex is not locked, Tcl error is thrown.	 While
		     waiting on the cond, the command releases mutex.	Before
		     returning	to the calling thread, the command re-acquires
		     the mutex again. Unlocking the mutex and waiting  on  the
		     condition variable cond is done atomically.

		     The ms command option, if given, must be an integer spec‐
		     ifying time interval in milliseconds the command waits to
		     be	 signalled.   Otherwise the command waits on condition
		     notify forever.

		     In multithreading programs,  there	 are  many  situations
		     where a thread has to wait for some event to happen until
		     it is allowed to proceed.	This is	 usually  accomplished
		     by repeatedly testing a condition under the mutex protec‐
		     tion and waiting on the condition variable until the con‐
		     dition evaluates to true:
			 set mutex [thread::mutex create]
			 set cond  [thread::cond  create]

			 thread::mutex lock $mutex
			 while {<some_condition_is_true>} {
			     thread::cond wait $cond $mutex
			 }
			 # Do some work under mutex protection
			 thread::mutex unlock $mutex
		     Repeated  testing	of  the	 condition is needed since the
		     condition variable may get signalled without  the	condi‐
		     tion  being  actually  changed (spurious thread wake-ups,
		     for example).

DISCUSSION
       The fundamental threading model in Tcl is that there can be one or more
       Tcl  interpreters  per  thread, but each Tcl interpreter should only be
       used by a single thread which created it.  A "shared  memory"  abstrac‐
       tion  is	 awkward to provide in Tcl because Tcl makes assumptions about
       variable and data ownership. Therefore this extension supports a simple
       form  of threading where the main thread can manage several background,
       or "worker" threads.  For example,  an  event-driven  server  can  pass
       requests	 to  worker  threads,  and  then  await	 responses from worker
       threads or new client requests. Everything goes through the common  Tcl
       event  loop,  so	 message  passing between threads works naturally with
       event-driven I/O, vwait on variables, and so forth. For the transfer of
       bulk information it is possible to move channels between the threads.

       For  advanced  multithreading scripts, script-level access to two basic
       synchronization primitives, mutex and condition variables, is also sup‐
       ported.

SEE ALSO
       http://www.tcl.tk/doc/howto/thread_model.html, tpool, tsv, ttrace

KEYWORDS
       events, message passing, mutex, synchronization, thread

Tcl Threading			      2.7			     thread(n)
[top]

List of man pages available for OpenMandriva

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net