Added suggestions for how to handle the multithreaded case. [Bug 2844962]

2 files changed, 34 insertions, 19 deletions

diff --git a/ChangeLog b/ChangeLog
index 85fcec9..c913e45 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,11 +1,15 @@
+2009-09-03  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/LinkVar.3: [Bug 2844962]: Added documentation of issues relating
+	to use of this API in a multi-threaded environment.
+
 2009-09-01  Andreas Kupries  <andreask@activestate.com>
 
 	* generic/tclIORTrans.c (ReflectInput): Remove error response to
-	0-result from method 'limit?' of transformations. Return the
-	number of copied bytes instead, which is possibly nothing. The
-	latter then triggers EOF handling in the higher layers, making the
-	0-result of limit? the way to inject artificial EOF's into the
-	data stream.
+	0-result from method 'limit?' of transformations. Return the number of
+	copied bytes instead, which is possibly nothing. The latter then
+	triggers EOF handling in the higher layers, making the 0-result of
+	limit? the way to inject artificial EOF's into the data stream.
 
 2009-09-01  Don Porter  <dgp@users.sourceforge.net>
 
@@ -16,32 +20,32 @@
 
 2009-08-27  Don Porter  <dgp@users.sourceforge.net>
 
-	* generic/tclStringObj.c:       A few more string overflow cases in
-	[format].  [Bug 2845535]
+	* generic/tclStringObj.c:       [Bug 2845535]: A few more string
+	overflow cases in [format].
 
 2009-08-25  Andreas Kupries  <andreask@activestate.com>
 
-	* generic/tclBasic.c (Tcl_CreateInterp, Tcl_EvalTokensStandard,
-	Tcl_EvalEx, TclEvalEx, TclAdvanceContinuations, TclNREvalObjEx):
+	* generic/tclBasic.c (Tcl_CreateInterp, Tcl_EvalTokensStandard)
+	(Tcl_EvalEx, TclEvalEx, TclAdvanceContinuations, TclNREvalObjEx):
 	* generic/tclCmdMZ.c (Tcl_SwitchObjCmd, TclListLines):
 	* generic/tclCompCmds.c (*):
-	* generic/tclCompile.c (TclSetByteCodeFromAny, TclInitCompileEnv,
-	TclFreeCompileEnv, TclCompileScript, TclCompileTokens):
+	* generic/tclCompile.c (TclSetByteCodeFromAny, TclInitCompileEnv)
+	(TclFreeCompileEnv, TclCompileScript, TclCompileTokens):
 	* generic/tclCompile.h (CompileEnv):
 	* generic/tclInt.h (ContLineLoc, Interp):
-	* generic/tclObj.c (ThreadSpecificData, ContLineLocFree,
-	TclThreadFinalizeObjects, TclInitObjSubsystem,
-	TclContinuationsEnter, TclContinuationsEnterDerived,
-	TclContinuationsCopy, TclContinuationsGet, TclFreeObj):
+	* generic/tclObj.c (ThreadSpecificData, ContLineLocFree)
+	(TclThreadFinalizeObjects, TclInitObjSubsystem, TclContinuationsEnter,
+	(TclContinuationsEnterDerived, TclContinuationsCopy, TclFreeObj)
+	(TclContinuationsGet):
 	* generic/tclParse.c (TclSubstTokens, Tcl_SubstObj):
 	* generic/tclProc.c (TclCreateProc):
 	* generic/tclVar.c (TclPtrSetVar):
 	* tests/info.test (info-30.0-24):
 
 	Extended the parser, compiler, and execution engine with code and
-	attendant data structures tracking the position of continuation
-	lines which are not visible in the resulting script Tcl_Obj*'s, to
-	properly account for them while counting lines for #280.
+	attendant data structures tracking the position of continuation lines
+	which are not visible in the resulting script Tcl_Obj*'s, to properly
+	account for them while counting lines for #280.
 
 2009-08-24  Daniel Steffen  <das@users.sourceforge.net>
 
diff --git a/doc/LinkVar.3 b/doc/LinkVar.3
index ad6d5f6..5ff0565 100644
--- a/doc/LinkVar.3
+++ b/doc/LinkVar.3
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: LinkVar.3,v 1.17 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: LinkVar.3,v 1.18 2009/09/03 08:07:07 dkf Exp $
 '\" 
 .so man.macros
 .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures"
@@ -194,5 +194,16 @@ Tk widget that wishes to display the value of the variable), the
 trace will not trigger when the C variable has changed.
 \fBTcl_UpdateLinkedVar\fR ensures that any traces on the Tcl
 variable are invoked.
+.PP
+Note that, as with any call to a Tcl interpreter, \fBTcl_UpdateLinkedVar\fR
+must be called from the same thread that created the interpreter. The safest
+mechanism is to ensure that the C variable is only ever updated from the same
+thread that created the interpreter (possibly in response to an event posted
+with \fBTcl_ThreadQueueEvent\fR), but when it is necessary to update the
+variable in a separate thread, it is advised that \fBTcl_AsyncMark\fR be used
+to indicate to the thread hosting the interpreter that it is ready to run
+\fBTcl_UpdateLinkedVar\fR.
+.SH "SEE ALSO"
+Tcl_TraceVar(3)
 .SH KEYWORDS
 boolean, integer, link, read-only, real, string, traces, variable