doc/next: add notes for new #cgo annotations

Fixes #56378

Change-Id: Ibeaa5aa67e017be0da8797e4c87abf2ee0249db8
Reviewed-on: https://go-review.googlesource.com/c/go/+/632015
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Commit-Queue: Ian Lance Taylor <iant@google.com>

diff --git a/doc/next/3-tools.md b/doc/next/3-tools.md
index c09cea6d84f2b3fd30305d50ed583616aca15152..cf2f17830d499e5a52c0b181ba71e4636d17d6d3 100644 (file)
--- a/doc/next/3-tools.md
+++ b/doc/next/3-tools.md
@@ -14,6 +14,14 @@ a test integration system, you can revert to the text build output by setting
 
 ### Cgo {#cgo}
 
+Cgo supports new annotations for C functions to improve run time
+performance.
+`#cgo noescape cFunctionName` tells the compiler that memory passed to
+the C function `cFunctionname` does not escape.
+`#cgo nocallback cFunctionName` tells the compiler that the C function
+`cFunctionName` does not call back to any Go functions.
+For more information, see [the cgo documentation](/pkg/cmd/cgo#hdr-Optimizing_calls_of_C_code).
+
 Cgo currently refuses to compile calls to a C function which has multiple
 incompatible declarations. For instance, if `f` is declared as both `void f(int)`
 and `void f(double)`, cgo will report an error instead of possibly generating an