Tcl Source Code

Check-in [a68b3f0dac]
Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:First draft of the necessary doc changes.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | bug-57945b574a
Files: files | file ages | folders
SHA1: a68b3f0dacc138bd6f43bdd364a3002289e4a671
User & Date: mistachkin 2015-05-16 06:49:00
Context
2015-05-16
06:59
Reword and clarify the doc changes from the previous check-in. check-in: 4b7f255148 user: mistachkin tags: bug-57945b574a
06:49
First draft of the necessary doc changes. check-in: a68b3f0dac user: mistachkin tags: bug-57945b574a
2015-04-09
19:53
Add new public Tcl C API to allow a mutex to be unlocked and then finalized atomically. Candidate f... check-in: 30dc11630f user: mistachkin tags: bug-57945b574a
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to doc/Thread.3.

5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
..
31
32
33
34
35
36
37



38
39
40
41
42
43
44
...
134
135
136
137
138
139
140
141



142
143
144

145
146
147
148
149
150
151
152
...
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
.TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH NAME
Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread support
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
void
\fBTcl_ConditionNotify\fR(\fIcondPtr\fR)
.sp
................................................................................
.sp
void
\fBTcl_MutexUnlock\fR(\fImutexPtr\fR)
.sp
void
\fBTcl_MutexFinalize\fR(\fImutexPtr\fR)
.sp



int
\fBTcl_CreateThread\fR(\fIidPtr, proc, clientData, stackSize, flags\fR)
.sp
int
\fBTcl_JoinThread\fR(\fIid, result\fR)
.SH ARGUMENTS
.AS Tcl_CreateThreadProc proc out
................................................................................
for handling event queuing in multithreaded applications.  See
the \fBNotifier\fR manual page for more information on these procedures.
.PP
A mutex is a lock that is used to serialize all threads through a piece
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.
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.
The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR

procedures are defined as empty macros if not compiling with threads enabled.
For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used.
This macro assures correct mutex handling even when the core is compiled
without threads enabled.
.PP
A condition variable is used as a signaling mechanism:
a thread can lock a mutex and then wait on a condition variable
with \fBTcl_ConditionWait\fR.  This atomically releases the mutex lock
................................................................................
.SS INITIALIZATION
.PP
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 \fBTcl_MutexFinalize\fR or
\fBTcl_ConditionFinalize\fR.
Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR.
.SH "SCRIPT-LEVEL ACCESS TO THREADS"
.PP
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 facilities only via C
interfaces, and leaves it up to packages to expose these matters to






|







 







>
>
>







 







|
>
>
>


|
>
|







 







|
|







5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
..
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
...
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
...
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
.TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH NAME
Tcl_ConditionNotify, Tcl_ConditionWait, Tcl_ConditionFinalize, Tcl_GetThreadData, Tcl_MutexLock, Tcl_MutexUnlock, Tcl_MutexFinalize, Tcl_MutexUnlockAndFinalize, Tcl_CreateThread, Tcl_JoinThread \- Tcl thread support
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
void
\fBTcl_ConditionNotify\fR(\fIcondPtr\fR)
.sp
................................................................................
.sp
void
\fBTcl_MutexUnlock\fR(\fImutexPtr\fR)
.sp
void
\fBTcl_MutexFinalize\fR(\fImutexPtr\fR)
.sp
void
\fBTcl_MutexUnlockAndFinalize\fR(\fImutexPtr\fR)
.sp
int
\fBTcl_CreateThread\fR(\fIidPtr, proc, clientData, stackSize, flags\fR)
.sp
int
\fBTcl_JoinThread\fR(\fIid, result\fR)
.SH ARGUMENTS
.AS Tcl_CreateThreadProc proc out
................................................................................
for handling event queuing in multithreaded applications.  See
the \fBNotifier\fR manual page for more information on these procedures.
.PP
A mutex is a lock that is used to serialize all threads through a piece
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.
A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR or
\fBTcl_MutexUnlockAndFinalize\fR.  It is illegal to destroy a locked mutex
with \fBTcl_MutexFinalize\fR; however, it is legal to destroy a locked mutex
with \fBTcl_MutexUnlockAndFinalize\fR.
The result of locking a mutex twice from the same thread is undefined.
On some platforms it will result in a deadlock.
The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR, \fBTcl_MutexFinalize\fR, and
\fBTcl_MutexUnlockAndFinalize\fR procedures are defined as empty macros if
not compiling with threads enabled.
For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used.
This macro assures correct mutex handling even when the core is compiled
without threads enabled.
.PP
A condition variable is used as a signaling mechanism:
a thread can lock a mutex and then wait on a condition variable
with \fBTcl_ConditionWait\fR.  This atomically releases the mutex lock
................................................................................
.SS INITIALIZATION
.PP
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 \fBTcl_MutexFinalize\fR (or
\fBTcl_MutexUnlockAndFinalize\fR) and \fBTcl_ConditionFinalize\fR.
Thread local storage is reclaimed during \fBTcl_FinalizeThread\fR.
.SH "SCRIPT-LEVEL ACCESS TO THREADS"
.PP
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 facilities only via C
interfaces, and leaves it up to packages to expose these matters to