diff options
| author | Craig Jennings <c@cjennings.net> | 2025-08-14 22:58:58 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2025-08-14 22:58:58 -0500 |
| commit | 82ba818ff456bcd6d56a06226e3f27e98fbb55c3 (patch) | |
| tree | 158cfc17b2f644a10f063cb546752cfaae12c97f /devdocs/go/runtime%2Fcgo%2Findex.html | |
| parent | 9278ddd4ea1a8b1a4c1edaa8894516e3f48d245b (diff) | |
| download | dotemacs-82ba818ff456bcd6d56a06226e3f27e98fbb55c3.tar.gz dotemacs-82ba818ff456bcd6d56a06226e3f27e98fbb55c3.zip | |
removing all downloaded devdocs files
Diffstat (limited to 'devdocs/go/runtime%2Fcgo%2Findex.html')
| -rw-r--r-- | devdocs/go/runtime%2Fcgo%2Findex.html | 96 |
1 files changed, 0 insertions, 96 deletions
diff --git a/devdocs/go/runtime%2Fcgo%2Findex.html b/devdocs/go/runtime%2Fcgo%2Findex.html deleted file mode 100644 index 1f504a91..00000000 --- a/devdocs/go/runtime%2Fcgo%2Findex.html +++ /dev/null @@ -1,96 +0,0 @@ -<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> |
