syscall: improve NewCallback documentation and panic message

Fixes #26138

Change-Id: If77b2839bccc600223735df42438a19131cd051c
GitHub-Last-Rev: 64ceaea9f1cb7afb3d552dce0223b818bac1faf9
GitHub-Pull-Request: golang/go#26617
Reviewed-on: https://go-review.googlesource.com/126035
Reviewed-by: Austin Clements <austin@google.com>
Run-TryBot: Austin Clements <austin@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>

diff --git a/src/runtime/syscall_windows.go b/src/runtime/syscall_windows.go
index 5ab78fdbf20a56b8eaa3a29e1decbd5805c75f7b..8264070569ff360ea1beeccb82e43da40b21fa2d 100644 (file)
--- a/src/runtime/syscall_windows.go
+++ b/src/runtime/syscall_windows.go
@@ -42,20 +42,20 @@ func callbackasmAddr(i int) uintptr {
 //go:linkname compileCallback syscall.compileCallback
 func compileCallback(fn eface, cleanstack bool) (code uintptr) {
        if fn._type == nil || (fn._type.kind&kindMask) != kindFunc {
-               panic("compileCallback: not a function")
+               panic("compileCallback: expected function with one uintptr-sized result")
        }
        ft := (*functype)(unsafe.Pointer(fn._type))
        if len(ft.out()) != 1 {
-               panic("compileCallback: function must have one output parameter")
+               panic("compileCallback: expected function with one uintptr-sized result")
        }
        uintptrSize := unsafe.Sizeof(uintptr(0))
        if ft.out()[0].size != uintptrSize {
-               panic("compileCallback: output parameter size is wrong")
+               panic("compileCallback: expected function with one uintptr-sized result")
        }
        argsize := uintptr(0)
        for _, t := range ft.in() {
                if t.size > uintptrSize {
-                       panic("compileCallback: input parameter size is wrong")
+                       panic("compileCallback: argument size is larger than uintptr")
                }
                argsize += uintptrSize
        }

diff --git a/src/syscall/syscall_windows.go b/src/syscall/syscall_windows.go
index 5cfdb76e2bf5bbc972f3c9269c8b366b26cc4037..b234f3d67d4cea28cfcbf38e6efb10e644e6184c 100644 (file)
--- a/src/syscall/syscall_windows.go
+++ b/src/syscall/syscall_windows.go
@@ -120,16 +120,16 @@ func (e Errno) Timeout() bool {
 // Implemented in runtime/syscall_windows.go.
 func compileCallback(fn interface{}, cleanstack bool) uintptr
 
-// Converts a Go function to a function pointer conforming
-// to the stdcall calling convention. This is useful when
-// interoperating with Windows code requiring callbacks.
+// NewCallback converts a Go function to a function pointer conforming to the stdcall calling convention.
+// This is useful when interoperating with Windows code requiring callbacks.
+// The argument is expected to be a function with with one uintptr-sized result. The function must not have arguments with size larger than the size of uintptr.
 func NewCallback(fn interface{}) uintptr {
        return compileCallback(fn, true)
 }
 
-// Converts a Go function to a function pointer conforming
-// to the cdecl calling convention. This is useful when
-// interoperating with Windows code requiring callbacks.
+// NewCallbackCDecl converts a Go function to a function pointer conforming to the cdecl calling convention.
+// This is useful when interoperating with Windows code requiring callbacks.
+// The argument is expected to be a function with with one uintptr-sized result. The function must not have arguments with size larger than the size of uintptr.
 func NewCallbackCDecl(fn interface{}) uintptr {
        return compileCallback(fn, false)
 }