From 0a3fb69a270dd2873ab8e2ed5116a2a18060dcb6 Mon Sep 17 00:00:00 2001 From: Michael Schaller Date: Tue, 23 Dec 2014 16:32:26 +0100 Subject: [PATCH] [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. --- Doc/Manual/Go.html | 59 +++++++++++++++++++++++++++++----------------- 1 file 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 @@
-

23.3 A tour of basic C/C++ wrapping

+

23.4 A tour of basic C/C++ wrapping

@@ -238,7 +250,7 @@ modifications have to occur. This section briefly covers the essential aspects of this wrapping.

-

23.3.1 Go Package Name

+

23.4.1 Go Package Name

@@ -248,7 +260,7 @@ directive. You may override this by using SWIG's -package command line option.

-

23.3.2 Go Names

+

23.4.2 Go Names

@@ -280,7 +292,7 @@ followed by that name, and the destructor will be named Delete followed by that name.

-

23.3.3 Go Constants

+

23.4.3 Go Constants

@@ -288,7 +300,7 @@ C/C++ constants created via #define or the %constant directive become Go constants, declared with a const declaration. -

23.3.4 Go Enumerations

+

23.4.4 Go Enumerations

@@ -298,7 +310,7 @@ usual). The values of the enumeration will become variables in Go; code should avoid modifying those variables.

-

23.3.5 Go Classes

+

23.4.5 Go Classes

@@ -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.

-

23.3.5.1 Go Class Memory Management

+

23.4.5.1 Go Class Memory Management

Calling NewClassName for some C++ class ClassName 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 DeleteClassName. +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 DeleteClassName.

A common technique is to store the C++ object into a Go object, and -use the Go function runtime.SetFinalizer 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 runtime.SetFinalizer to free the C++ object when +the Go object is freed. It is strongly recommended to read the +runtime.SetFinalizer +documentation before using this technique to understand its limitations. +For example, if the SWIG package is imported as "wrap": 

@@ -409,7 +424,7 @@ func NewGoClassName() *GoClassName {
-

23.3.5.2 Go Class Inheritance

+

23.4.5.2 Go Class Inheritance

@@ -421,7 +436,7 @@ Doing the reverse will require an explicit type assertion, which will be checked dynamically.

-

23.3.6 Go Templates

+

23.4.6 Go Templates

@@ -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 %template directive. -

23.3.7 Go Director Classes

+

23.4.7 Go Director Classes

@@ -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++.

-

23.3.8 Default Go primitive type mappings

+

23.4.8 Default Go primitive type mappings

@@ -579,7 +594,7 @@ that typemap, or add new values, to control how C/C++ types are mapped into Go types.

-

23.3.9 Output arguments

+

23.4.9 Output arguments

Because of limitations in the way output arguments are processed in swig, @@ -632,7 +647,7 @@ void f(char *output); -

23.3.10 Adding additional go code

+

23.4.10 Adding additional go code

Often the APIs generated by swig are not very natural in go, especially if @@ -727,7 +742,7 @@ func bar() { -

23.3.11 Go typemaps

+

23.4.11 Go typemaps