summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorkupries <kupries>2000-04-04 20:28:40 (GMT)
committerkupries <kupries>2000-04-04 20:28:40 (GMT)
commit654b797828a64252043684a8896212e371fbb59d (patch)
tree2d5993ba2241ee288fdaac5cde72d36fba00b349 /doc
parent10736d4e37e044b5393fb9069608f7188ef0d9b3 (diff)
downloadtcl-654b797828a64252043684a8896212e371fbb59d.zip
tcl-654b797828a64252043684a8896212e371fbb59d.tar.gz
tcl-654b797828a64252043684a8896212e371fbb59d.tar.bz2
2000-04-03 Andreas Kupries <a.kupries@westend.com>
* Overall change: Definition of public API's for the finalization of conditions and mutexes. [Bug: 4199]. * generic/tclInt.h: Removed definitions of TclFinalizeMutex and TclFinalizeCondition. * generic/tcl.decls: Added declarations of Tcl_MutexFinalize and Tcl_ConditionFinalize. * generic/tclThread.c: Renamed TclFinalizeMutex to Tcl_MutexFinalize. Renamed TclFinalizeCondition to Tcl_ConditionFinalize. * generic/tclNotify.c: Changed usage of TclFinalizeMutex to Tcl_MutexFinalize. * unix/tclUnixNotfy.c: * generic/tclThreadTest.c: Changed usages of TclFinalizeCondition to Tcl_ConditionFinalize. * generic/tcl.h: Added empty macros for Tcl_MutexFinalize and Tcl_ConditionFinalize, to be used when the core is compiled without threads. * doc/Thread.3: Added description the new API's.
Diffstat (limited to 'doc')
-rw-r--r--doc/Thread.332
1 files changed, 27 insertions, 5 deletions
diff --git a/doc/Thread.3 b/doc/Thread.3
index 9e473b8..cd50dbc 100644
--- a/doc/Thread.3
+++ b/doc/Thread.3
@@ -5,13 +5,15 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: Thread.3,v 1.7 1999/08/21 19:40:48 hobbs Exp $
+'\" RCS: @(#) $Id: Thread.3,v 1.8 2000/04/04 20:28:40 kupries Exp $
'\"
.so man.macros
.TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock \- Tcl thread support.
+Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize,
+Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize
+\- Tcl thread support.
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -22,6 +24,9 @@ void
void
\fBTcl_ConditionWait\fR(\fIcondPtr, mutexPtr, timePtr\fR)
.sp
+void
+\fBTcl_ConditionFinalize\fR(\fIcondPtr\fR)
+.sp
Void *
\fBTcl_GetThreadData\fR(\fIkeyPtr, size\fR)
.sp
@@ -30,6 +35,9 @@ void
.sp
void
\fBTcl_MutexUnlock\fR(\fImutexPtr\fR)
+.sp
+void
+\fBTcl_MutexFinalize\fR(\fImutexPtr\fR)
.SH ARGUMENTS
.AS Tcl_ThreadDataKey *keyPtr
.AP Tcl_Condition *condPtr in
@@ -89,10 +97,11 @@ of code by calling \fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR.
If one thread holds a mutex, any other thread calling \fBTcl_MutexLock\fR will
block until \fBTcl_MutexUnlock\fR is called.
.VS
+A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR.
The result of locking a mutex twice from the same thread is undefined.
On some platforms it will result in a deadlock.
.VE
-\fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR
+The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR
procedures are defined as empty macros if not compiling with threads enabled.
.PP
A condition variable is used as a signaling mechanism:
@@ -111,6 +120,15 @@ The caller of \fBTcl_ConditionWait\fR should be prepared for spurious
notifications by calling \fBTcl_ConditionWait\fR within a while loop
that tests some invariant.
.PP
+.VS
+A condition variable can be destroyed after its use by calling
+\fBTcl_ConditionFinalize\fR.
+.PP
+The \fBTcl_ConditionNotify\fR, \fBTcl_ConditionWait\fR and
+\fBTcl_ConditionFinalize\fR procedures are defined as empty macros if
+not compiling with threads enabled.
+.VE
+.PP
The \fBTcl_GetThreadData\fR 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
@@ -122,8 +140,12 @@ 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
-cleaned up by process exit handlers. Thread local storage is
-reclaimed during \fBTcl_FinalizeThread\fR.
+.VS
+either cleaned up by process exit handlers (if living that long) or
+explicitly by calls to \fBTcl_MutexFinalize\fR or
+\fBTcl_ConditionFinalize\fR.
+.VE
+Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR.
.SH "CREATING THREADS"
The API to create threads is not finalized at this time.
There are private facilities to create threads that contain a new