diff options
Diffstat (limited to 'devdocs/go/runtime%2Fcgo%2Findex.html')
| -rw-r--r-- | devdocs/go/runtime%2Fcgo%2Findex.html | 96 |
1 files changed, 96 insertions, 0 deletions
diff --git a/devdocs/go/runtime%2Fcgo%2Findex.html b/devdocs/go/runtime%2Fcgo%2Findex.html new file mode 100644 index 00000000..1f504a91 --- /dev/null +++ b/devdocs/go/runtime%2Fcgo%2Findex.html @@ -0,0 +1,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> |