qbit/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-11-26 05:07:59 -07:00
Code Releases Activity

runtime/cgo: clarify Handle documentation

Browse Source 
Fixes #45427

Change-Id: Ic67630a5f39d8789a4a30c6b4ee30946bc50382e
Reviewed-on: https://go-review.googlesource.com/c/go/+/308230
Trust: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Ainar Garipov <gugl.zadolbal@gmail.com>
Reviewed-by: Changkun Ou <euryugasaki@gmail.com>
Reviewed-by: Emmanuel Odeke <emmanuel@orijtech.com>
This commit is contained in:
Ian Lance Taylor 2021-04-07 15:22:53 -07:00
parent bb76193a7f
commit 7e583806d8
1 changed files with 37 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
src/runtime/cgo/handle.go
View File

@ -9,50 +9,56 @@ import (
"sync/atomic"
)
// Handle provides a safe representation of Go values to pass between
// Go and C. The zero value of a handle is not a valid handle, and thus
// is safe to use as a sentinel in C APIs.
// 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.
//
// 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.
// 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.
//
// For instance, on the Go side:
//
// package main
// package main
//
// /*
// #include <stdint.h> // for uintptr_t
// /*
// #include <stdint.h> // for uintptr_t
//
// extern void MyGoPrint(uintptr_t handle);
// void myprint(uintptr_t handle);
// */
// import "C"
// import "runtime/cgo"
// 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().(int)
// println(val)
// h.Delete()
// }
// //export MyGoPrint
// func MyGoPrint(handle C.uintptr_t) {
// h := cgo.Handle(handle)
// val := h.Value().(string)
// println(val)
// h.Delete()
// }
//
// func main() {
// val := 42
// C.myprint(C.uintptr_t(cgo.NewHandle(val)))
// // Output: 42
// }
// func main() {
// val := "hello Go"
// C.myprint(C.uintptr_t(cgo.NewHandle(val)))
// // Output: hello Go
// }
//
// and on the C side:
//
// #include <stdint.h> // for uintptr_t
// #include <stdint.h> // for uintptr_t
//
// // A Go function
// extern void MyGoPrint(uintptr_t handle);
// // A Go function
// extern void MyGoPrint(uintptr_t handle);
//
// // A C function
// void myprint(uintptr_t handle) {
// MyGoPrint(handle);
// }
// // A C function
// void myprint(uintptr_t handle) {
// MyGoPrint(handle);
// }
type Handle uintptr
// NewHandle returns a handle for a given value.