diff options
Diffstat (limited to 'Doc/Manual/Go.html')
| -rw-r--r-- | Doc/Manual/Go.html | 223 |
1 files changed, 208 insertions, 15 deletions
diff --git a/Doc/Manual/Go.html b/Doc/Manual/Go.html index 93b87a4a4..9a6de9598 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> @@ -23,6 +24,7 @@ <li><a href="#Go_enumerations">Go Enumerations</a> <li><a href="#Go_classes">Go Classes</a> <ul> +<li><a href="#Go_class_memory">Go Class Memory Management</a> <li><a href="#Go_class_inheritance">Go Class Inheritance</a> </ul> <li><a href="#Go_templates">Go Templates</a> @@ -30,6 +32,7 @@ <li><a href="#Go_primitive_type_mappings">Default Go primitive type mappings</a> <li><a href="#Go_output_arguments">Output arguments</a> <li><a href="#Go_adding_additional_code">Adding additional go code</a> +<li><a href="#Go_typemaps">Go typemaps</a> </ul> </ul> </div> @@ -67,7 +70,22 @@ 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://golang.org/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> +<p> +The examples in the 2nd link are shipped with the SWIG distribution under the Examples/go directory. +</p> + + +<H2><a name="Go_running_swig"></a>23.3 Running SWIG with Go</H2> <p> @@ -76,7 +94,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> @@ -150,7 +168,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 @@ -226,7 +244,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> @@ -236,7 +254,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> @@ -246,7 +264,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> @@ -278,7 +296,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> @@ -286,7 +304,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> @@ -296,7 +314,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> @@ -374,7 +392,43 @@ 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_inheritance"></a>23.3.5.1 Go Class Inheritance</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 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. 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> +type GoClassName struct { + w wrap.ClassName +} + +func NewGoClassName() *GoClassName { + r := &GoClassName{wrap.NewClassName()} + runtime.SetFinalizer(r, + func(r *GoClassName) { + wrap.DeleteClassName(r.w) + }) + return r +} +</pre> +</div> + +<H4><a name="Go_class_inheritance"></a>23.4.5.2 Go Class Inheritance</H4> <p> @@ -386,7 +440,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> @@ -394,7 +448,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> @@ -437,7 +491,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> @@ -544,7 +598,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, @@ -597,7 +651,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 @@ -692,5 +746,144 @@ func bar() { </pre> </div> +<H3><a name="Go_typemaps"></a>23.4.11 Go typemaps</H3> + + +<p> +You can use the <tt>%typemap</tt> directive to modify SWIG's default +wrapping behavior for specific C/C++ types. You need to be familiar +with the material in the general +"<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. That chapter +explains how to define a typemap. This section describes some +specific typemaps used for Go. +</p> + +<p> +In general type conversion code may be written either in C/C++ or in +Go. The choice to make normally depends on where memory should be +allocated. To allocate memory controlled by the Go garbage collector, +write Go code. To allocate memory in the C/C++ heap, write C code. +</p> + +<table BORDER summary="Go Typemaps"> +<tr> +<td><b>Typemap</b></td> +<td><b>Description</b></td> +</tr> + +<tr> +<td>gotype</td> +<td> +The Go type to use for a C++ type. This type will appear in the +generated Go wrapper function. If this is not defined SWIG will use a +default as <a href="#Go_primitive_type_mappings">described above</a>. +</td> +</tr> + +<tr> +<td>imtype</td> +<td> +An intermediate Go type used by the "goin", "goout", "godirectorin", +and "godirectorout" typemaps. If this typemap is not defined for a +C/C++ type, the gotype typemape will be used. This is useful when +gotype is best converted to C/C++ using Go code. +</td> +</tr> + +<tr> +<td>goin</td> +<td> +Go code to convert from gotype to imtype when calling a C/C++ +function. SWIG will then internally convert imtype to a C/C++ type +and pass it down. If this is not defined no conversion is done. +</td> +</tr> + +<tr> +<td>in</td> +<td> +C/C++ code to convert the internally generated C/C++ type, based on +imtype, into the C/C++ type that a function call expects. If this is +not defined the value will simply be cast to the desired type. +</td> +</tr> + +<tr> +<td>out</td> +<td> +C/C++ code to convert the C/C++ type that a function call returns into +the internally generated C/C++ type, based on imtype, that will be +returned to Go. If this is not defined the value will simply be cast +to the desired type. +</td> +</tr> + +<tr> +<td>goout</td> +<td> +Go code to convert a value returned from a C/C++ function from imtype +to gotype. If this is not defined no conversion is done. +</td> +</tr> + +<tr> +<td>argout</td> +<td> +C/C++ code to adjust an argument value when returning from a function. +This is called after the real C/C++ function has run. This uses the +internally generated C/C++ type, based on imtype. This is only useful +for a pointer type of some sort. If this is not defined nothing will +be done. +</td> +</tr> + +<tr> +<td>goargout</td> +<td> +Go code to adjust an argument value when returning from a function. +This is called after the real C/C++ function has run. The value will +be in imtype. This is only useful for a pointer type of some sort. +If this is not defined nothing will be done. +</td> +</tr> + +<tr> +<td>directorin</td> +<td> +C/C++ code to convert the C/C++ type used to call a director method +into the internally generated C/C++ type, based on imtype, that will +be passed to Go. If this is not defined the value will simply be cast +to the desired type. +</td> +</tr> + +<tr> +<td>godirectorin</td> +<td> +Go code to convert a value used to call a director method from imtype +to gotype. If this is not defined no conversion is done. +</td> +</tr> + +<tr> +<td>godirectorout</td> +<td> +Go code to convert a value returned from a director method from gotype +to imtype. If this is not defined no conversion is done. +</td> +</tr> + +<tr> +<td>directorout</td> +<td> +C/C++ code to convert a value returned from a director method from the +internally generated C/C++ type, based on imtype, into the type that +the method should return If this is not defined the value will simply +be cast to the desired type. +</td> +</tr> + +</table> + </body> </html> |