mirror of
https://github.com/golang/go
synced 2024-11-11 20:50:23 -07:00
runtime/cgo: clarify Handle documentation
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:
parent
bb76193a7f
commit
7e583806d8
@ -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.
|
||||
|
Loading…
Reference in New Issue
Block a user