syscall: document NewCallback and NewCallbackCDecl limitations

Currently NewCallback and NewCallbackCDecl may only be called a limited
number of times in a single Go process, but this property of the API is
not documented. This change fixes that, but does not document the
precise limit to avoid making that limit part of the API, leaving us
open to increasing or decreasing the limit in the future as needed.

Although the API avoids documenting a limit, it does guarantee a minimum
callback count so users can rely on at least some amount of callbacks
working.

Updates #46184.

Change-Id: I5129bf5fe301efff73ac112ba1f207ab32058833
Reviewed-on: https://go-review.googlesource.com/c/go/+/321133
Trust: Michael Knyszek <mknyszek@google.com>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

1 files changed, 6 insertions, 0 deletions

diff --git a/src/syscall/syscall_windows.go b/src/syscall/syscall_windows.go
index fa0b5d959a..fc734effbb 100644
--- a/src/syscall/syscall_windows.go
+++ b/src/syscall/syscall_windows.go
@@ -174,6 +174,9 @@ func compileCallback(fn interface{}, cleanstack bool) uintptr
 // 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 one uintptr-sized result. The function must not have arguments with size larger than the size of uintptr.
+// Only a limited number of callbacks may be created in a single Go process, and any memory allocated
+// for these callbacks is never released.
+// Between NewCallback and NewCallbackCDecl, at least 1024 callbacks can always be created.
 func NewCallback(fn interface{}) uintptr {
 	return compileCallback(fn, true)
 }
@@ -181,6 +184,9 @@ func NewCallback(fn interface{}) uintptr {
 // 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 one uintptr-sized result. The function must not have arguments with size larger than the size of uintptr.
+// Only a limited number of callbacks may be created in a single Go process, and any memory allocated
+// for these callbacks is never released.
+// Between NewCallback and NewCallbackCDecl, at least 1024 callbacks can always be created.
 func NewCallbackCDecl(fn interface{}) uintptr {
 	return compileCallback(fn, false)
 }