[Go] Add documentation note about Go and C++ exceptions.

For #418
Fixes #518

3 files changed, 29 insertions, 13 deletions

diff --git a/CHANGES.current b/CHANGES.current
index b131dd6d6..a9a67201d 100644
--- a/CHANGES.current
+++ b/CHANGES.current
@@ -7,6 +7,9 @@ the issue number to the end of the URL: https://github.com/swig/swig/issues/
 Version 4.1.0 (in progress)
 ===========================
 
+2022-03-15: ianlancetaylor
+	    [Go] Add documentation note about Go and C++ exceptions.
+
 2022-03-12: wsfulton
             #1524 %interface family of macros no longer contain the getter/setter
             methods for wrapping variables. The interface only contains
diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html
index a62f4ed12..6b33b99db 100644
--- a/Doc/Manual/Contents.html
+++ b/Doc/Manual/Contents.html
@@ -878,6 +878,7 @@
 </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_exceptions">Go and C++ Exceptions</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 66e1973fe..cbe93a35e 100644
--- a/Doc/Manual/Go.html
+++ b/Doc/Manual/Go.html
@@ -30,6 +30,7 @@
 </ul>
 <li><a href="#Go_templates">Go Templates</a>
 <li><a href="#Go_threads">Go and C/C++ Threads</a>
+<li><a href="#Go_exceptions">Go and C++ Exceptions</a>
 <li><a href="#Go_director_classes">Go Director Classes</a>
 <ul>
 <li><a href="#Go_director_example_cpp_code">Example C++ code</a>
@@ -573,7 +574,18 @@ the <a href="https://pkg.go.dev/runtime#LockOSThread"><code>runtime.LockOSThread
 function to lock the goroutine onto a single thread.
 </p>
 
-<H3><a name="Go_director_classes">25.4.8 Go Director Classes</a></H3>
+<H3><a name="Go_exceptions">25.4.8 Go and C++ Exceptions</a></H3>
+
+
+<p>
+C++ exceptions do not interoperate with Go code.  Attempts to throw
+C++ exceptions through a Go caller are unreliable: in many cases the
+C++ exception handler will be unable to unwind the stack, and the
+program will crash.  The only safe way to handle C++ exceptions is to
+catch them in C++ before returning to Go.
+</p>
+
+<H3><a name="Go_director_classes">25.4.9 Go Director Classes</a></H3>
 
 
 <p>
@@ -591,7 +603,7 @@ completely to avoid common pitfalls with directors in Go.
 </p>
 
 
-<H4><a name="Go_director_example_cpp_code">25.4.8.1 Example C++ code</a></H4>
+<H4><a name="Go_director_example_cpp_code">25.4.9.1 Example C++ code</a></H4>
 
 
 <p>
@@ -663,7 +675,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.8.2 Enable director feature</a></H4>
+<H4><a name="Go_director_enable">25.4.9.2 Enable director feature</a></H4>
 
 
 <p>
@@ -698,7 +710,7 @@ documentation on directors.
 </p>
 
 
-<H4><a name="Go_director_ctor_dtor">25.4.8.3 Constructor and destructor</a></H4>
+<H4><a name="Go_director_ctor_dtor">25.4.9.3 Constructor and destructor</a></H4>
 
 
 <p>
@@ -751,7 +763,7 @@ embedding</a>.
 </p>
 
 
-<H4><a name="Go_director_overriding">25.4.8.4 Override virtual methods</a></H4>
+<H4><a name="Go_director_overriding">25.4.9.4 Override virtual methods</a></H4>
 
 
 <p>
@@ -819,7 +831,7 @@ the Go methods.
 </p>
 
 
-<H4><a name="Go_director_base_methods">25.4.8.5 Call base methods</a></H4>
+<H4><a name="Go_director_base_methods">25.4.9.5 Call base methods</a></H4>
 
 
 <p>
@@ -856,7 +868,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.8.6 Subclass via embedding</a></H4>
+<H4><a name="Go_director_subclass">25.4.9.6 Subclass via embedding</a></H4>
 
 
 <p>
@@ -924,7 +936,7 @@ class.
 </p>
 
 
-<H4><a name="Go_director_finalizer">25.4.8.7 Memory management with runtime.SetFinalizer</a></H4>
+<H4><a name="Go_director_finalizer">25.4.9.7 Memory management with runtime.SetFinalizer</a></H4>
 
 
 <p>
@@ -989,7 +1001,7 @@ before using <tt>runtime.SetFinalizer</tt> to know all of its gotchas.
 </p>
 
 
-<H4><a name="Go_director_foobargo_class">25.4.8.8 Complete FooBarGo example class</a></H4>
+<H4><a name="Go_director_foobargo_class">25.4.9.8 Complete FooBarGo example class</a></H4>
 
 
 <p>
@@ -1118,7 +1130,7 @@ SWIG/Examples/go/director/</a>.
 </p>
 
 
-<H3><a name="Go_primitive_type_mappings">25.4.9 Default Go primitive type mappings</a></H3>
+<H3><a name="Go_primitive_type_mappings">25.4.10 Default Go primitive type mappings</a></H3>
 
 
 <p>
@@ -1225,7 +1237,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.10 Output arguments</a></H3>
+<H3><a name="Go_output_arguments">25.4.11 Output arguments</a></H3>
 
 
 <p>Because of limitations in the way output arguments are processed in swig,
@@ -1278,7 +1290,7 @@ void f(char *output);
 </pre>
 </div>
 
-<H3><a name="Go_adding_additional_code">25.4.11 Adding additional go code</a></H3>
+<H3><a name="Go_adding_additional_code">25.4.12 Adding additional go code</a></H3>
 
 
 <p>Often the APIs generated by swig are not very natural in go, especially if
@@ -1373,7 +1385,7 @@ func bar() {
 </pre>
 </div>
 
-<H3><a name="Go_typemaps">25.4.12 Go typemaps</a></H3>
+<H3><a name="Go_typemaps">25.4.13 Go typemaps</a></H3>
 
 
 <p>