diff options
author | Michael Schaller <michael@5challer.de> | 2014-12-23 16:32:26 +0100 |
---|---|---|
committer | Michael Schaller <michael@5challer.de> | 2014-12-24 11:03:17 +0100 |
commit | 0a3fb69a270dd2873ab8e2ed5116a2a18060dcb6 (patch) | |
tree | 6a54467b45dbe16e04c415d1b83ccc52c019b169 | |
parent | 5c57a8c877f88c9388b68067d665c63546244ba0 (diff) | |
download | swig-0a3fb69a270dd2873ab8e2ed5116a2a18060dcb6.tar.gz |
[Go] Updated Go documentation (examples, runtime.SetFinalizer, object ownership).
* Fixes swig/swig#266.
* Added links to working examples.
* Added link to runtime.SetFinalizer documentation.
* Added recommendation to read the runtime.SetFinalizer documentation before using it.
* Clarified that C++ objects ownership is not tracked and thus objects need to be freed manually.
-rw-r--r-- | Doc/Manual/Go.html | 59 |
1 files changed, 37 insertions, 22 deletions
diff --git a/Doc/Manual/Go.html b/Doc/Manual/Go.html index 03b48d40c..d0d7f4c51 100644 --- a/Doc/Manual/Go.html +++ b/Doc/Manual/Go.html @@ -10,6 +10,7 @@ <div class="sectiontoc"> <ul> <li><a href="#Go_overview">Overview</a> +<li><a href="#Go_examples">Examples</a> <li><a href="#Go_running_swig">Running SWIG with Go</a> <ul> <li><a href="#Go_commandline">Additional Commandline Options</a> @@ -69,7 +70,18 @@ checking and runtime library are not used with Go. This should be borne in mind when reading the rest of the SWIG documentation. </p> -<H2><a name="Go_running_swig"></a>23.2 Running SWIG with Go</H2> +<H2><a name="Go_examples"></a>23.2 Examples</H2> + + +<p> +Working examples can be found here: +</p> +<ul> +<li><a href="https://github.com/golang/go/tree/master/misc/swig">Examples from the Go source tree</a> +<li><a href="https://github.com/swig/swig/tree/master/Examples/go">Examples from the SWIG source tree</a> +</ul> + +<H2><a name="Go_running_swig"></a>23.3 Running SWIG with Go</H2> <p> @@ -78,7 +90,7 @@ default SWIG will generate code for the gc compilers. To generate code for gccgo, you should also use the <tt>-gccgo</tt> option. </p> -<H3><a name="Go_commandline"></a>23.2.1 Additional Commandline Options</H3> +<H3><a name="Go_commandline"></a>23.3.1 Additional Commandline Options</H3> <p> @@ -152,7 +164,7 @@ swig -go -help </table> -<H3><a name="Go_outputs"></a>23.2.2 Go Output Files</H3> +<H3><a name="Go_outputs"></a>23.3.2 Go Output Files</H3> <p> When generating Go code, SWIG will generate the following @@ -228,7 +240,7 @@ this: % go tool 6l main.6 </pre></div> -<H2><a name="Go_basic_tour"></a>23.3 A tour of basic C/C++ wrapping</H2> +<H2><a name="Go_basic_tour"></a>23.4 A tour of basic C/C++ wrapping</H2> <p> @@ -238,7 +250,7 @@ modifications have to occur. This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Go_package"></a>23.3.1 Go Package Name</H3> +<H3><a name="Go_package"></a>23.4.1 Go Package Name</H3> <p> @@ -248,7 +260,7 @@ directive. You may override this by using SWIG's <tt>-package</tt> command line option. </p> -<H3><a name="Go_names"></a>23.3.2 Go Names</H3> +<H3><a name="Go_names"></a>23.4.2 Go Names</H3> <p> @@ -280,7 +292,7 @@ followed by that name, and the destructor will be named <tt>Delete</tt> followed by that name. </p> -<H3><a name="Go_constants"></a>23.3.3 Go Constants</H3> +<H3><a name="Go_constants"></a>23.4.3 Go Constants</H3> <p> @@ -288,7 +300,7 @@ C/C++ constants created via <tt>#define</tt> or the <tt>%constant</tt> directive become Go constants, declared with a <tt>const</tt> declaration. -<H3><a name="Go_enumerations"></a>23.3.4 Go Enumerations</H3> +<H3><a name="Go_enumerations"></a>23.4.4 Go Enumerations</H3> <p> @@ -298,7 +310,7 @@ usual). The values of the enumeration will become variables in Go; code should avoid modifying those variables. </p> -<H3><a name="Go_classes"></a>23.3.5 Go Classes</H3> +<H3><a name="Go_classes"></a>23.4.5 Go Classes</H3> <p> @@ -376,21 +388,24 @@ returns a go interface. If the returned pointer can be null, you can check for this by calling the Swigcptr() method. </p> -<H4><a name="Go_class_memory"></a>23.3.5.1 Go Class Memory Management</H4> +<H4><a name="Go_class_memory"></a>23.4.5.1 Go Class Memory Management</H4> <p> Calling <tt>NewClassName</tt> for some C++ class <tt>ClassName</tt> will allocate memory using the C++ memory allocator. This memory will -not be automatically freed by Go's garbage collector. When you are -done with the C++ object you must free it using <tt>DeleteClassName</tt>. +not be automatically freed by Go's garbage collector as the object ownership is +not tracked. When you are done with the C++ object you must free it manually +using <tt>DeleteClassName</tt>. </p> <p> A common technique is to store the C++ object into a Go object, and -use the Go function <tt>runtime.SetFinalizer</tt> to free the C++ -object when the Go object is freed. For example, if the SWIG package -is imported as "wrap": +use the Go function <tt>runtime.SetFinalizer</tt> to free the C++ object when +the Go object is freed. It is strongly recommended to read the +<a href="https://golang.org/pkg/runtime/#SetFinalizer">runtime.SetFinalizer</a> +documentation before using this technique to understand its limitations. +For example, if the SWIG package is imported as "wrap": </p> <div class="code"> <pre> @@ -409,7 +424,7 @@ func NewGoClassName() *GoClassName { </pre> </div> -<H4><a name="Go_class_inheritance"></a>23.3.5.2 Go Class Inheritance</H4> +<H4><a name="Go_class_inheritance"></a>23.4.5.2 Go Class Inheritance</H4> <p> @@ -421,7 +436,7 @@ Doing the reverse will require an explicit type assertion, which will be checked dynamically. </p> -<H3><a name="Go_templates"></a>23.3.6 Go Templates</H3> +<H3><a name="Go_templates"></a>23.4.6 Go Templates</H3> <p> @@ -429,7 +444,7 @@ In order to use C++ templates in Go, you must tell SWIG to create wrappers for a particular template instantation. To do this, use the <tt>%template</tt> directive. -<H3><a name="Go_director_classes"></a>23.3.7 Go Director Classes</H3> +<H3><a name="Go_director_classes"></a>23.4.7 Go Director Classes</H3> <p> @@ -472,7 +487,7 @@ method defined in Go. The Go code may of course call other methods on itself, and those methods may be defined either in Go or in C++. </p> -<H3><a name="Go_primitive_type_mappings"></a>23.3.8 Default Go primitive type mappings</H3> +<H3><a name="Go_primitive_type_mappings"></a>23.4.8 Default Go primitive type mappings</H3> <p> @@ -579,7 +594,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"></a>23.3.9 Output arguments</H3> +<H3><a name="Go_output_arguments"></a>23.4.9 Output arguments</H3> <p>Because of limitations in the way output arguments are processed in swig, @@ -632,7 +647,7 @@ void f(char *output); </pre> </div> -<H3><a name="Go_adding_additional_code"></a>23.3.10 Adding additional go code</H3> +<H3><a name="Go_adding_additional_code"></a>23.4.10 Adding additional go code</H3> <p>Often the APIs generated by swig are not very natural in go, especially if @@ -727,7 +742,7 @@ func bar() { </pre> </div> -<H3><a name="Go_typemaps"></a>23.3.11 Go typemaps</H3> +<H3><a name="Go_typemaps"></a>23.4.11 Go typemaps</H3> <p> |