new repository

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 &lt;stdint.h&gt; // 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 &lt;stdint.h&gt; // 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(&amp;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">
+    &copy; 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>