Go docs: add note on thread local storage

Fixes #374

2 files changed, 33 insertions, 17 deletions

diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html
index 07cd1e723..89d04a026 100644
--- a/Doc/Manual/Contents.html
+++ b/Doc/Manual/Contents.html
@@ -874,6 +874,7 @@
 <li><a href="Go.html#Go_class_inheritance">Go Class Inheritance</a>
 </ul>
 <li><a href="Go.html#Go_templates">Go Templates</a>
+<li><a href="Go.html#Go_threads">Go and C/C++ Threads</a>
 <li><a href="Go.html#Go_director_classes">Go Director Classes</a>
 <ul>
 <li><a href="Go.html#Go_director_example_cpp_code">Example C++ code</a>
diff --git a/Doc/Manual/Go.html b/Doc/Manual/Go.html
index 4e230c78b..66e1973fe 100644
--- a/Doc/Manual/Go.html
+++ b/Doc/Manual/Go.html
@@ -29,6 +29,7 @@
 <li><a href="#Go_class_inheritance">Go Class Inheritance</a>
 </ul>
 <li><a href="#Go_templates">Go Templates</a>
+<li><a href="#Go_threads">Go and C/C++ Threads</a>
 <li><a href="#Go_director_classes">Go Director Classes</a>
 <ul>
 <li><a href="#Go_director_example_cpp_code">Example C++ code</a>
@@ -494,10 +495,6 @@ The usage of Go finalizers is problematic with C++'s RAII idiom as it isn't
 predictable when the finalizer will run and this might require a Close or Delete
 method to be added the Go object that stores a C++ object to mitigate.
 </li>
-<li>
-The Go finalizer function typically runs in a different OS thread which can be
-problematic with C++ code that uses thread-local storage.
-</li>
 </ul>
 
 <p>
@@ -557,8 +554,26 @@ In order to use C++ templates in Go, you must tell SWIG to create
 wrappers for a particular template instantiation.  To do this, use
 the <tt>%template</tt> directive.
 
+<H3><a name="Go_threads">25.4.7 Go and C/C++ Threads</a></H3>
+
+
+<p>
+C and C++ code can use operating system threads and thread local
+storage.  Go code uses goroutines, which are multiplexed onto
+operating system threads.  This multiplexing means that Go code can
+change to run on a different thread at any time.  C/C++ code, on the
+other hand, may assume that it runs on a single thread; this is true
+in particular if the C/C++ code uses thread local storage.
+</p>
+
+<p>
+In order to use Go code with C/C++ code that expects to run on a
+single thread, the Go code must call
+the <a href="https://pkg.go.dev/runtime#LockOSThread"><code>runtime.LockOSThread</code></a>
+function to lock the goroutine onto a single thread.
+</p>
 
-<H3><a name="Go_director_classes">25.4.7 Go Director Classes</a></H3>
+<H3><a name="Go_director_classes">25.4.8 Go Director Classes</a></H3>
 
 
 <p>
@@ -576,7 +591,7 @@ completely to avoid common pitfalls with directors in Go.
 </p>
 
 
-<H4><a name="Go_director_example_cpp_code">25.4.7.1 Example C++ code</a></H4>
+<H4><a name="Go_director_example_cpp_code">25.4.8.1 Example C++ code</a></H4>
 
 
 <p>
@@ -648,7 +663,7 @@ be found in <a href="#Go_director_foobargo_class">the end of the guide</a>.
 </p>
 
 
-<H4><a name="Go_director_enable">25.4.7.2 Enable director feature</a></H4>
+<H4><a name="Go_director_enable">25.4.8.2 Enable director feature</a></H4>
 
 
 <p>
@@ -683,7 +698,7 @@ documentation on directors.
 </p>
 
 
-<H4><a name="Go_director_ctor_dtor">25.4.7.3 Constructor and destructor</a></H4>
+<H4><a name="Go_director_ctor_dtor">25.4.8.3 Constructor and destructor</a></H4>
 
 
 <p>
@@ -736,7 +751,7 @@ embedding</a>.
 </p>
 
 
-<H4><a name="Go_director_overriding">25.4.7.4 Override virtual methods</a></H4>
+<H4><a name="Go_director_overriding">25.4.8.4 Override virtual methods</a></H4>
 
 
 <p>
@@ -804,7 +819,7 @@ the Go methods.
 </p>
 
 
-<H4><a name="Go_director_base_methods">25.4.7.5 Call base methods</a></H4>
+<H4><a name="Go_director_base_methods">25.4.8.5 Call base methods</a></H4>
 
 
 <p>
@@ -841,7 +856,7 @@ be found in <a href="#Go_director_foobargo_class">the end of the guide</a>.
 </p>
 
 
-<H4><a name="Go_director_subclass">25.4.7.6 Subclass via embedding</a></H4>
+<H4><a name="Go_director_subclass">25.4.8.6 Subclass via embedding</a></H4>
 
 
 <p>
@@ -909,7 +924,7 @@ class.
 </p>
 
 
-<H4><a name="Go_director_finalizer">25.4.7.7 Memory management with runtime.SetFinalizer</a></H4>
+<H4><a name="Go_director_finalizer">25.4.8.7 Memory management with runtime.SetFinalizer</a></H4>
 
 
 <p>
@@ -974,7 +989,7 @@ before using <tt>runtime.SetFinalizer</tt> to know all of its gotchas.
 </p>
 
 
-<H4><a name="Go_director_foobargo_class">25.4.7.8 Complete FooBarGo example class</a></H4>
+<H4><a name="Go_director_foobargo_class">25.4.8.8 Complete FooBarGo example class</a></H4>
 
 
 <p>
@@ -1103,7 +1118,7 @@ SWIG/Examples/go/director/</a>.
 </p>
 
 
-<H3><a name="Go_primitive_type_mappings">25.4.8 Default Go primitive type mappings</a></H3>
+<H3><a name="Go_primitive_type_mappings">25.4.9 Default Go primitive type mappings</a></H3>
 
 
 <p>
@@ -1210,7 +1225,7 @@ that typemap, or add new values, to control how C/C++ types are mapped
 into Go types.
 </p>
 
-<H3><a name="Go_output_arguments">25.4.9 Output arguments</a></H3>
+<H3><a name="Go_output_arguments">25.4.10 Output arguments</a></H3>
 
 
 <p>Because of limitations in the way output arguments are processed in swig,
@@ -1263,7 +1278,7 @@ void f(char *output);
 </pre>
 </div>
 
-<H3><a name="Go_adding_additional_code">25.4.10 Adding additional go code</a></H3>
+<H3><a name="Go_adding_additional_code">25.4.11 Adding additional go code</a></H3>
 
 
 <p>Often the APIs generated by swig are not very natural in go, especially if
@@ -1358,7 +1373,7 @@ func bar() {
 </pre>
 </div>
 
-<H3><a name="Go_typemaps">25.4.11 Go typemaps</a></H3>
+<H3><a name="Go_typemaps">25.4.12 Go typemaps</a></H3>
 
 
 <p>