blob: 1f504a9121dbc4a7b39017e3f73de3e8bbd1eede (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
<h1> Package cgo </h1> <ul id="short-nav">
<li><code>import "runtime/cgo"</code></li>
<li><a href="#pkg-overview" class="overviewLink">Overview</a></li>
<li><a href="#pkg-index" class="indexLink">Index</a></li>
</ul> <h2 id="pkg-overview">Overview </h2> <p>Package cgo contains runtime support for code generated by the cgo tool. See the documentation for the cgo command for details on using cgo. </p> <h2 id="pkg-index">Index </h2> <ul id="manual-nav">
<li><a href="#Handle">type Handle</a></li>
<li> <a href="#NewHandle">func NewHandle(v any) Handle</a>
</li>
<li> <a href="#Handle.Delete">func (h Handle) Delete()</a>
</li>
<li> <a href="#Handle.Value">func (h Handle) Value() any</a>
</li>
<li><a href="#Incomplete">type Incomplete</a></li>
</ul> <h3>Package files</h3> <p> <span>callbacks.go</span> <span>callbacks_traceback.go</span> <span>cgo.go</span> <span>handle.go</span> <span>iscgo.go</span> <span>linux.go</span> <span>mmap.go</span> <span>setenv.go</span> <span>sigaction.go</span> </p> <h2 id="Handle">type <span>Handle</span> </h2> <p>Handle provides a way to pass values that contain Go pointers (pointers to memory allocated by Go) between Go and C without breaking the cgo pointer passing rules. A Handle is an integer value that can represent any Go value. A Handle can be passed through C and back to Go, and Go code can use the Handle to retrieve the original Go value. </p>
<p>The underlying type of Handle is guaranteed to fit in an integer type that is large enough to hold the bit pattern of any pointer. The zero value of a Handle is not valid, and thus is safe to use as a sentinel in C APIs. </p>
<p>For instance, on the Go side: </p>
<pre data-language="go">package main
/*
#include <stdint.h> // for uintptr_t
extern void MyGoPrint(uintptr_t handle);
void myprint(uintptr_t handle);
*/
import "C"
import "runtime/cgo"
//export MyGoPrint
func MyGoPrint(handle C.uintptr_t) {
h := cgo.Handle(handle)
val := h.Value().(string)
println(val)
h.Delete()
}
func main() {
val := "hello Go"
C.myprint(C.uintptr_t(cgo.NewHandle(val)))
// Output: hello Go
}
</pre> <p>and on the C side: </p>
<pre data-language="go">#include <stdint.h> // for uintptr_t
// A Go function
extern void MyGoPrint(uintptr_t handle);
// A C function
void myprint(uintptr_t handle) {
MyGoPrint(handle);
}
</pre> <p>Some C functions accept a void* argument that points to an arbitrary data value supplied by the caller. It is not safe to coerce a <a href="#Handle">cgo.Handle</a> (an integer) to a Go <span>unsafe.Pointer</span>, but instead we can pass the address of the cgo.Handle to the void* parameter, as in this variant of the previous example: </p>
<pre data-language="go">package main
/*
extern void MyGoPrint(void *context);
static inline void myprint(void *context) {
MyGoPrint(context);
}
*/
import "C"
import (
"runtime/cgo"
"unsafe"
)
//export MyGoPrint
func MyGoPrint(context unsafe.Pointer) {
h := *(*cgo.Handle)(context)
val := h.Value().(string)
println(val)
h.Delete()
}
func main() {
val := "hello Go"
h := cgo.NewHandle(val)
C.myprint(unsafe.Pointer(&h))
// Output: hello Go
}
</pre> <pre data-language="go">type Handle uintptr</pre> <h3 id="NewHandle">func <span>NewHandle</span> </h3> <pre data-language="go">func NewHandle(v any) Handle</pre> <p>NewHandle returns a handle for a given value. </p>
<p>The handle is valid until the program calls Delete on it. The handle uses resources, and this package assumes that C code may hold on to the handle, so a program must explicitly call Delete when the handle is no longer needed. </p>
<p>The intended use is to pass the returned handle to C code, which passes it back to Go, which calls Value. </p>
<h3 id="Handle.Delete">func (Handle) <span>Delete</span> </h3> <pre data-language="go">func (h Handle) Delete()</pre> <p>Delete invalidates a handle. This method should only be called once the program no longer needs to pass the handle to C and the C code no longer has a copy of the handle value. </p>
<p>The method panics if the handle is invalid. </p>
<h3 id="Handle.Value">func (Handle) <span>Value</span> </h3> <pre data-language="go">func (h Handle) Value() any</pre> <p>Value returns the associated Go value for a valid handle. </p>
<p>The method panics if the handle is invalid. </p>
<h2 id="Incomplete">type <span>Incomplete</span> </h2> <p>Incomplete is used specifically for the semantics of incomplete C types. </p>
<pre data-language="go">type Incomplete struct {
// contains filtered or unexported fields
}
</pre><div class="_attribution">
<p class="_attribution-p">
© Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br>
<a href="http://golang.org/pkg/runtime/cgo/" class="_attribution-link">http://golang.org/pkg/runtime/cgo/</a>
</p>
</div>
|
