[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.
This commit is contained in:
Michael Schaller
parent
5c57a8c877
commit
0a3fb69a27
1 changed files with 37 additions and 22 deletions
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue