DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_ConditionNotify(3tcl)




Threads(3)           Tcl Library Procedures            Threads(3)

_________________________________________________________________


NAME

     Tcl_ConditionNotify,                      Tcl_ConditionWait,
     Tcl_ConditionFinalize,   Tcl_GetThreadData,   Tcl_MutexLock,
     Tcl_MutexUnlock,    Tcl_MutexFinalize,     Tcl_CreateThread,
     Tcl_JoinThread - Tcl thread support


SYNOPSIS

     #include <tcl.h>

     void
     Tcl_ConditionNotify(condPtr)

     void
     Tcl_ConditionWait(condPtr, mutexPtr, timePtr)

     void
     Tcl_ConditionFinalize(condPtr)

     Void *
     Tcl_GetThreadData(keyPtr, size)

     void
     Tcl_MutexLock(mutexPtr)

     void
     Tcl_MutexUnlock(mutexPtr)

     void
     Tcl_MutexFinalize(mutexPtr)

     int
     Tcl_CreateThread(idPtr, threadProc, clientData, stackSize, flags)

     int
     Tcl_JoinThread(id, result)


ARGUMENTS

     Tcl_Condition *condPtr (in)                   A    condition
                                                   variable,
                                                   which must  be
                                                   associated
                                                   with  a  mutex
                                                   lock.

     Tcl_Mutex *mutexPtr (in)                      A mutex lock.

     Tcl_Time *timePtr (in)                        A  time  limit
                                                   on  the condi-
                                                   tion     wait.
                                                   NULL  to  wait

Tcl                     Last change: 8.1                        1

Threads(3)           Tcl Library Procedures            Threads(3)

                                                   forever.  Note
                                                   that a polling
                                                   value   of   0
                                                   seconds   does
                                                   not make  much
                                                   sense.

     Tcl_ThreadDataKey *keyPtr (in)                This   identi-
                                                   fies  a  block
                                                   of      thread
                                                   local storage.
                                                   The key should
                                                   be  static and
                                                   process-wide,
                                                   yet       each
                                                   thread    will
                                                   end up associ-
                                                   ating  a  dif-
                                                   ferent   block
                                                   of     storage
                                                   with this key.

     int *size (in)                                The  size   of
                                                   the     thread
                                                   local  storage
                                                   block.    This
                                                   amount of data
                                                   is   allocated
                                                   and   initial-
                                                   ized  to  zero
                                                   the first time
                                                   each    thread
                                                   calls
                                                   Tcl_GetThreadData.

     Tcl_ThreadId *idPtr (out)                     The   referred
                                                   storage   will
                                                   contain the id
                                                   of  the  newly
                                                   created thread
                                                   as returned by
                                                   the  operating
                                                   system.

     Tcl_ThreadId id (in)                          Id   of    the
                                                   thread  waited
                                                   upon.

     Tcl_ThreadCreateProc threadProc (in)          This procedure
                                                   will   act  as
                                                   the main()  of
                                                   the      newly

Tcl                     Last change: 8.1                        2

Threads(3)           Tcl Library Procedures            Threads(3)

                                                   created
                                                   thread.    The
                                                   specified
                                                   clientData
                                                   will  be   its
                                                   sole argument.

     ClientData clientData (in)                    Arbitrary
                                                   information.
                                                   Passed as sole
                                                   argument    to
                                                   the    thread-
                                                   Proc.

     int stackSize (in)                            The  size   of
                                                   the      stack
                                                   given  to  the
                                                   new thread.

     int flags (in)                                Bitmask   con-
                                                   taining  flags
                                                   allowing   the
                                                   caller      to
                                                   modify
                                                   behaviour   of
                                                   the        new
                                                   thread.

     int *result (out)                             The   referred
                                                   storage     is
                                                   used to  place
                                                   the  exit code
                                                   of the  thread
                                                   waited    upon
                                                   into it.
_________________________________________________________________


INTRODUCTION

     Beginning with the 8.1 release, the Tcl core is thread safe,
     which  allows  you  to  incorporate  Tcl  into multithreaded
     applications without customizing the Tcl  core.   To  enable
     Tcl  multithreading  support, you must include the --enable-
     threads option to configure when you configure  and  compile
     your Tcl core.

     An important constraint of the Tcl threads implementation is
     that  only the thread that created a Tcl interpreter can use
     that interpreter.  In other words, multiple threads can  not
     access  the same Tcl interpreter.  (However, a single thread
     can safely create and use multiple interpreters.)

Tcl                     Last change: 8.1                        3

Threads(3)           Tcl Library Procedures            Threads(3)


DESCRIPTION

     Tcl provides  Tcl_CreateThread  for  creating  threads.  The
     caller  can determine the size of the stack given to the new
     thread and modify the behaviour through the supplied  flags.
     The  value  TCL_THREAD_STACK_DEFAULT for the stackSize indi-
     cates that the default size as specified  by  the  operating
     system  is  to be used for the new thread. As for the flags,
     currently   only   the   values    TCL_THREAD_NOFLAGS    and
     TCL_THREAD_JOINABLE  are  defined. The first of them invokes
     the default behaviour with no specialties. Using the  second
     value  marks  the  new  thread  as joinable. This means that
     another thread can wait for the such marked thread  to  exit
     and join it.

     Restrictions: On some UNIX systems the pthread-library  does
     not contain the functionality to specify the stack size of a
     thread. The specified value for the stack size is ignored on
     these  systems.  Windows currently does not support joinable
     threads. This flag value is therefore ignored on this  plat-
     form.

     Tcl provides the Tcl_ExitThread and Tcl_FinalizeThread func-
     tions  for  terminating  threads  and invoking optional per-
     thread exit handlers.  See the Tcl_Exit page for more infor-
     mation on these procedures.

     The Tcl_JoinThread function is provided to allow threads  to
     wait  upon  the exit of another thread, which must have been
     marked    as    joinable    through     usage     of     the
     TCL_THREAD_JOINABLE-flag    during    its    creation    via
     Tcl_CreateThread.

     Trying to wait for the exit of a non-joinable  thread  or  a
     thread which is already waited upon will result in an error.
     Waiting for a joinable thread which already exited is possi-
     ble,  the system will retain the necessary information until
     after the call to Tcl_JoinThread.  This means that not  cal-
     ling  Tcl_JoinThread  for  a  joinable  thread  will cause a
     memory leak.

     The Tcl_GetThreadData call returns a pointer to a  block  of
     thread-private  data.   Its argument is a key that is shared
     by all threads and a size for the  block  of  storage.   The
     storage  is  automatically  allocated and initialized to all
     zeros the first time each thread asks for it.   The  storage
     is automatically deallocated by Tcl_FinalizeThread.

  SYNCHRONIZATION AND COMMUNICATION
     Tcl provides Tcl_ThreadQueueEvent  and  Tcl_ThreadAlert  for
     handling  event  queuing in multithreaded applications.  See
     the Notifier manual page for more information on these  pro-
     cedures.

Tcl                     Last change: 8.1                        4

Threads(3)           Tcl Library Procedures            Threads(3)

     A mutex is a lock that is  used  to  serialize  all  threads
     through  a  piece  of  code  by  calling  Tcl_MutexLock  and
     Tcl_MutexUnlock.  If one thread holds  a  mutex,  any  other
     thread    calling    Tcl_MutexLock    will    block    until
     Tcl_MutexUnlock is called.  A mutex can be  destroyed  after
     its use by calling Tcl_MutexFinalize.  The result of locking
     a mutex twice from the same thread is  undefined.   On  some
     platforms  it will result in a deadlock.  The Tcl_MutexLock,
     Tcl_MutexUnlock and Tcl_MutexFinalize procedures are defined
     as  empty macros if not compiling with threads enabled.  For
     declaration of mutexes the TCL_DECLARE_MUTEX macro should be
     used.   This  macro assures correct mutex handling even when
     the core is compiled without threads enabled.

     A condition variable is used as a  signaling  mechanism:   a
     thread  can  lock a mutex and then wait on a condition vari-
     able with Tcl_ConditionWait.  This atomically  releases  the
     mutex  lock  and  blocks  the  waiting  thread until another
     thread   calls   Tcl_ConditionNotify.    The    caller    of
     Tcl_ConditionNotify should have the associated mutex held by
     previously calling Tcl_MutexLock, but this is not  enforced.
     Notifying  the condition variable unblocks all threads wait-
     ing on the condition variable, but they do not proceed until
     the mutex is released with Tcl_MutexUnlock.  The implementa-
     tion of  Tcl_ConditionWait  automatically  locks  the  mutex
     before returning.

     The caller  of  Tcl_ConditionWait  should  be  prepared  for
     spurious notifications by calling Tcl_ConditionWait within a
     while loop that tests some invariant.

     A condition variable can be destroyed after its use by  cal-
     ling Tcl_ConditionFinalize.

     The     Tcl_ConditionNotify,      Tcl_ConditionWait      and
     Tcl_ConditionFinalize procedures are defined as empty macros
     if not compiling with threads enabled.

  INITIALIZATION
     All of these synchronization objects are  self-initializing.
     They  are implemented as opaque pointers that should be NULL
     upon first use.  The mutexes  and  condition  variables  are
     either  cleaned  up by process exit handlers (if living that
     long)  or  explicitly  by  calls  to  Tcl_MutexFinalize   or
     Tcl_ConditionFinalize.   Thread  local  storage is reclaimed
     during Tcl_FinalizeThread.


SCRIPT-LEVEL ACCESS TO THREADS

     Tcl provides no built-in commands  for  scripts  to  use  to  |
     create, manage, or join threads, nor any script-level access  |
     to mutex or condition variables.  It provides  such  facili-  |
     ties  only via C interfaces, and leaves it up to packages to  |

Tcl                     Last change: 8.1                        5

Threads(3)           Tcl Library Procedures            Threads(3)

     expose these matters to the script level.  One such  package  |
     is the Thread package.


SEE ALSO

     Tcl_GetCurrentThread(3),            Tcl_ThreadQueueEvent(3),
     Tcl_ThreadAlert(3),                       Tcl_ExitThread(3),
     Tcl_FinalizeThread(3),       Tcl_CreateThreadExitHandler(3),
     Tcl_DeleteThreadExitHandler(3), Thread


KEYWORDS

     thread, mutex, condition variable, thread local storage

Tcl                     Last change: 8.1                        6


Man(1) output converted with man2html