doc: add doc about C types that we map to uintptr instead of ptr

Update #22906
Update #21897

Change-Id: I73709b2fdac6981d4bc2f7dab0767f2dd7be3be5
Reviewed-on: https://go-review.googlesource.com/82917
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/doc/go1.10.html b/doc/go1.10.html
index 1644f3cdb2c47b41f006f66bc0a2eb39ec699292..f2b57e32f9c20275a200cca4881579cb278f269a 100644 (file)
--- a/doc/go1.10.html
+++ b/doc/go1.10.html
@@ -262,8 +262,6 @@ Go structs and Go arrays are not supported in the type signatures of cgo-exporte
 
 <p>
 TODO: CL 70890 "permit passing string values directly between Go and C."
-<br>
-TODO: CL 66332 "special case C ptr types to use uintptr."
 </p>
 
 <p>
@@ -279,6 +277,31 @@ Later <code>go</code> <code>build</code> commands refer to the <code>CC</code> e
 variable or else the built-in default.
 </p>
 
+<p>
+Cgo now translates some C types that would normally map to a pointer
+type in Go, to a <code>uintptr</code> instead. These types include
+the <code>CFTypeRef</code> hierarchy in Darwin's CoreFoundation
+framework and the <code>jobject</code> hierarchy in Java's JNI
+interface.
+</p>
+
+<p>
+These types must be <code>uintptr</code> on the Go side because they
+would otherwise confuse the Go garbage collector; they are sometimes
+not really pointers but data structures encoded in a pointer type.
+</p>
+
+<p>
+Because of this change, values of the affected types need to be
+zero-initialized with the constant <code>0</code> instead of the
+constant <code>nil</code>. Go 1.10 provides <code>gofix</code>
+modules to help with that rewrite:
+<pre>
+       go tool fix -r cftype <pkg>
+       go tool fix -r jni <pkg>
+</pre>
+</p>
+
 <p>
 For more details, see the <a href="/cmd/cgo/">cgo documentation</a>.
 </p>

diff --git a/src/cmd/cgo/doc.go b/src/cmd/cgo/doc.go
index c1bdf0659fa0d809ddf1965d8b8d0251486395a4..0b64b31d463a4a2f0fd74255bdf846de91e429fc 100644 (file)
--- a/src/cmd/cgo/doc.go
+++ b/src/cmd/cgo/doc.go
@@ -403,16 +403,35 @@ the CF*Ref types from the CoreFoundation library on Darwin, including:
        CFXMLParserRef
        CFXMLTreeRef
 
+Also the object types from Java's JNI interface:
+
+       jobject
+       jclass
+       jthrowable
+       jstring
+       jarray
+       jbooleanArray
+       jbyteArray
+       jcharArray
+       jshortArray
+       jintArray
+       jlongArray
+       jfloatArray
+       jdoubleArray
+       jobjectArray
+       jweak
+
 These types are uintptr on the Go side because they would otherwise
 confuse the Go garbage collector; they are sometimes not really
 pointers but data structures encoded in a pointer type. All operations
 on these types must happen in C. The proper constant to initialize an
 empty such reference is 0, not nil.
 
-This special case was introduced in Go 1.10. For auto-updating code
-from Go 1.9 and earlier, use the cftype rewrite in the Go fix tool:
+These special cases were introduced in Go 1.10. For auto-updating code
+from Go 1.9 and earlier, use the cftype or jni rewrites in the Go fix tool:
 
        go tool fix -r cftype <pkg>
+       go tool fix -r jni <pkg>
 
 It will replace nil with 0 in the appropriate places.