]> Cypherpunks repositories - gostls13.git/commitdiff
all: document legacy //go:linkname for modules with ≥20,000 dependents
authorRuss Cox <rsc@golang.org>
Wed, 22 May 2024 03:24:47 +0000 (23:24 -0400)
committerGopher Robot <gobot@golang.org>
Thu, 23 May 2024 00:18:55 +0000 (00:18 +0000)
For #67401.

Change-Id: Icc10ede72547d8020c0ba45e89d954822a4b2455
Reviewed-on: https://go-review.googlesource.com/c/go/+/587218
Auto-Submit: Russ Cox <rsc@golang.org>
Reviewed-by: Cherry Mui <cherryyz@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

18 files changed:
src/encoding/json/decode.go
src/encoding/json/encode.go
src/runtime/alg.go
src/runtime/checkptr.go
src/runtime/iface.go
src/runtime/linkname.go
src/runtime/malloc.go
src/runtime/map.go
src/runtime/map_fast32.go
src/runtime/map_fast64.go
src/runtime/map_faststr.go
src/runtime/mbarrier.go
src/runtime/mbitmap.go
src/runtime/mgc.go
src/runtime/panic.go
src/runtime/proc.go
src/runtime/slice.go
src/runtime/stubs.go

index ce566f7955692581cf477f0545c2338eae3f9b2b..efceecdf82b04dcc764891d43834969791d842ef 100644 (file)
@@ -17,6 +17,7 @@ import (
        "unicode"
        "unicode/utf16"
        "unicode/utf8"
+       _ "unsafe" // for linkname
 )
 
 // Unmarshal parses the JSON-encoded data and stores the result
@@ -1178,6 +1179,15 @@ func unquote(s []byte) (t string, ok bool) {
        return
 }
 
+// unquoteBytes should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname unquoteBytes
 func unquoteBytes(s []byte) (t []byte, ok bool) {
        if len(s) < 2 || s[0] != '"' || s[len(s)-1] != '"' {
                return
index bd55c7caf0e5a5d7706be3265866845a0c53d8d8..cb28feb279f6c0d5bb23e056b024f9473a188f46 100644 (file)
@@ -24,6 +24,7 @@ import (
        "sync"
        "unicode"
        "unicode/utf8"
+       _ "unsafe" // for linkname
 )
 
 // Marshal returns the JSON encoding of v.
@@ -591,6 +592,16 @@ func stringEncoder(e *encodeState, v reflect.Value, opts encOpts) {
 }
 
 // isValidNumber reports whether s is a valid JSON number literal.
+//
+// isValidNumber should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname isValidNumber
 func isValidNumber(s string) bool {
        // This function implements the JSON numbers grammar.
        // See https://tools.ietf.org/html/rfc7159#section-6
@@ -1045,6 +1056,16 @@ type field struct {
 // typeFields returns a list of fields that JSON should recognize for the given type.
 // The algorithm is breadth-first search over the set of structs to include - the top struct
 // and then any reachable anonymous structs.
+//
+// typeFields should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname typeFields
 func typeFields(t reflect.Type) structFields {
        // Anonymous fields to explore at the current level and the next.
        current := []field{}
index cab0abf5776313c899811ba0cac986340a6df524..42b332d244228d5eba5990bd39745df28c7ac545 100644 (file)
@@ -48,6 +48,16 @@ var useAeshash bool
 func memhash(p unsafe.Pointer, h, s uintptr) uintptr
 func memhash32(p unsafe.Pointer, h uintptr) uintptr
 func memhash64(p unsafe.Pointer, h uintptr) uintptr
+
+// strhash should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname strhash
 func strhash(p unsafe.Pointer, h uintptr) uintptr
 
 func strhashFallback(a unsafe.Pointer, h uintptr) uintptr {
index 810787bff57bc743bf5664c4f318d7452bf4f5ea..be64ae7f0cb8d99f73f9c4311c191271735af218 100644 (file)
@@ -76,6 +76,16 @@ func checkptrArithmetic(p unsafe.Pointer, originals []unsafe.Pointer) {
 // checkptrBase(p1) == checkptrBase(p2). However, the converse/inverse
 // is not necessarily true as allocations can have trailing padding,
 // and multiple variables may be packed into a single allocation.
+//
+// checkptrBase should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname checkptrBase
 func checkptrBase(p unsafe.Pointer) uintptr {
        // stack
        if gp := getg(); gp.stack.lo <= uintptr(p) && uintptr(p) < gp.stack.hi {
index 67e703869121bc08033da653ecf2b7e425eef1a8..94bc07e380dd54b4e54d296db9a2c0c74c85922c 100644 (file)
@@ -32,6 +32,15 @@ func itabHashFunc(inter *interfacetype, typ *_type) uintptr {
        return uintptr(inter.Type.Hash ^ typ.Hash)
 }
 
+// getitab should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname getitab
 func getitab(inter *interfacetype, typ *_type, canfail bool) *itab {
        if len(inter.Methods) == 0 {
                throw("internal error - misuse of itab")
@@ -379,6 +388,15 @@ func convT32(val uint32) (x unsafe.Pointer) {
        return
 }
 
+// convT64 should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname convT64
 func convT64(val uint64) (x unsafe.Pointer) {
        if val < uint64(len(staticuint64s)) {
                x = unsafe.Pointer(&staticuint64s[val])
@@ -389,6 +407,15 @@ func convT64(val uint64) (x unsafe.Pointer) {
        return
 }
 
+// convTstring should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname convTstring
 func convTstring(val string) (x unsafe.Pointer) {
        if val == "" {
                x = unsafe.Pointer(&zeroVal[0])
@@ -399,6 +426,15 @@ func convTstring(val string) (x unsafe.Pointer) {
        return
 }
 
+// convTslice should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname convTslice
 func convTslice(val []byte) (x unsafe.Pointer) {
        // Note: this must work for any element type, not just byte.
        if (*slice)(unsafe.Pointer(&val)).array == nil {
index ebad9e1972c8b8ea338d974ac9c1f63a010d4eac..1b8a321c1c24207d2c46fefdb394d7a3f9fb4547 100644 (file)
@@ -25,7 +25,6 @@ import _ "unsafe"
 //go:linkname cgoNoCallback
 //go:linkname gobytes
 //go:linkname gostringn
-//go:linkname throw
 
 // used in plugin
 //go:linkname doInit
index 0e43b7acf4f4ef4bfb8018f2d66a7364cb8ac066..5820ac8594abedf370734202eb2333bd474b14f6 100644 (file)
@@ -969,6 +969,7 @@ func (c *mcache) nextFree(spc spanClass) (v gclinkptr, s *mspan, shouldhelpgc bo
 // mallocgc should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
 //   - github.com/ugorji/go/codec
 //
 // Do not remove or change the type signature.
@@ -1425,6 +1426,7 @@ func newarray(typ *_type, n int) unsafe.Pointer {
 // reflect_unsafe_NewArray is meant for package reflect,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
 //   - github.com/goccy/json
 //   - github.com/modern-go/reflect2
 //
index d284acf8036883a5e4430b4d1925977e66d6922d..a55feb45fbf3f79c7d4a4ad3304768408dde9668 100644 (file)
@@ -283,6 +283,16 @@ func makemap64(t *maptype, hint int64, h *hmap) *hmap {
 // makemap_small implements Go map creation for make(map[k]v) and
 // make(map[k]v, hint) when hint is known to be at most bucketCnt
 // at compile time and the map needs to be allocated on the heap.
+//
+// makemap_small should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname makemap_small
 func makemap_small() *hmap {
        h := new(hmap)
        h.hash0 = uint32(rand())
@@ -591,6 +601,7 @@ func mapaccess2_fat(t *maptype, h *hmap, key, zero unsafe.Pointer) (unsafe.Point
 // mapassign should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
 //   - github.com/ugorji/go/codec
 //
 // Do not remove or change the type signature.
@@ -847,6 +858,7 @@ search:
 // mapiterinit should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
 //   - github.com/goccy/go-json
 //   - github.com/ugorji/go/codec
 //
@@ -903,6 +915,7 @@ func mapiterinit(t *maptype, h *hmap, it *hiter) {
 // mapiternext should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
 //   - github.com/ugorji/go/codec
 //
 // Do not remove or change the type signature.
index 98aa42ff6b9dbf448a12c376161f5c38cf873840..f3d830ea4387613dd012b37e92236d6c3cf07168 100644 (file)
@@ -102,6 +102,7 @@ func mapaccess2_fast32(t *maptype, h *hmap, key uint32) (unsafe.Pointer, bool) {
 // mapassign_fast32 should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
 //   - github.com/ugorji/go/codec
 //
 // Do not remove or change the type signature.
index ae3a8123c44d2d29ab9b5e523cd292a083655e26..29cee968cd5539763f9970a51bbccaef80bc8900 100644 (file)
@@ -102,6 +102,7 @@ func mapaccess2_fast64(t *maptype, h *hmap, key uint64) (unsafe.Pointer, bool) {
 // mapassign_fast64 should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
 //   - github.com/ugorji/go/codec
 //
 // Do not remove or change the type signature.
@@ -201,6 +202,7 @@ done:
 // mapassign_fast64ptr should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
 //   - github.com/ugorji/go/codec
 //
 // Do not remove or change the type signature.
index bef5d7f95afbaa07d071faba99590d07cc602bd6..1494348be72797d36979ba57d69f8cc95f3c8a9d 100644 (file)
@@ -212,6 +212,7 @@ dohash:
 // mapassign_faststr should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
 //   - github.com/ugorji/go/codec
 //
 // Do not remove or change the type signature.
index 5876d86fbd05c3d485a408ebae6bb0bae3648792..f09151d913446d65978c076c3fbd42229d6dc039 100644 (file)
@@ -391,6 +391,15 @@ func reflect_typedarrayclear(typ *_type, ptr unsafe.Pointer, len int) {
 // pointers, usually by checking typ.PtrBytes. However, ptr
 // does not have to point to the start of the allocation.
 //
+// memclrHasPointers should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname memclrHasPointers
 //go:nosplit
 func memclrHasPointers(ptr unsafe.Pointer, n uintptr) {
        // Pass nil for the type since we don't have one here anyway.
index e7a712377ba8168374010fdfe2993e8b412af931..689fac103ccff67cd3546e0fd488066e9a82aca1 100644 (file)
@@ -1261,6 +1261,15 @@ func badPointer(s *mspan, p, refBase, refOff uintptr) {
 // It is nosplit so it is safe for p to be a pointer to the current goroutine's stack.
 // Since p is a uintptr, it would not be adjusted if the stack were to move.
 //
+// findObject should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname findObject
 //go:nosplit
 func findObject(p, refBase, refOff uintptr) (base uintptr, s *mspan, objIndex uintptr) {
        s = spanOf(p)
index 1316af72baf1d4153ce31a9f6418d747114e5993..9bfcf06069d051045cb5b7cfa3c9f1e76160c1d8 100644 (file)
@@ -215,6 +215,16 @@ var gcphase uint32
 // If you change it, you must change builtin/runtime.go, too.
 // If you change the first four bytes, you must also change the write
 // barrier insertion code.
+//
+// writeBarrier should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname writeBarrier
 var writeBarrier struct {
        enabled bool    // compiler emits a check of this before calling write barrier
        pad     [3]byte // compiler uses 32-bit load for "enabled" field
index e68d857c6d786ed78891f351f7e834a8dc63cc6d..145b1a45b112573d6f5276ad834758289aeb8e98 100644 (file)
@@ -1034,6 +1034,15 @@ func sync_fatal(s string) {
 // NOTE: temporarily marked "go:noinline" pending investigation/fix of
 // issue #67274, so as to fix longtest builders.
 //
+// throw should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname throw
 //go:nosplit
 func throw(s string) {
        // Everything throw does should be recursively nosplit so it
index 12f26fbb6cdfd7ec7b90fb40e061108892859058..ba44f05c169024bdda022a00dd318f10cc7325e4 100644 (file)
@@ -4731,6 +4731,14 @@ func exitsyscall0(gp *g) {
 
 // Called from syscall package before fork.
 //
+// syscall_runtime_BeforeFork is for package syscall,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/containerd/containerd
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname syscall_runtime_BeforeFork syscall.runtime_BeforeFork
 //go:nosplit
 func syscall_runtime_BeforeFork() {
@@ -4752,6 +4760,14 @@ func syscall_runtime_BeforeFork() {
 
 // Called from syscall package after fork in parent.
 //
+// syscall_runtime_AfterFork is for package syscall,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/containerd/containerd
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname syscall_runtime_AfterFork syscall.runtime_AfterFork
 //go:nosplit
 func syscall_runtime_AfterFork() {
@@ -4777,6 +4793,14 @@ var inForkedChild bool
 // temporarily sharing address space with the parent process, this must
 // not change any global variables or calling into C code that may do so.
 //
+// syscall_runtime_AfterForkInChild is for package syscall,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/containerd/containerd
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname syscall_runtime_AfterForkInChild syscall.runtime_AfterForkInChild
 //go:nosplit
 //go:nowritebarrierrec
index 3439a0d751fb2eea1baf92da04e64a4a5d410c5d..7ffca036c029aec4ec194d63b4a5e9ef4eb4102a 100644 (file)
@@ -89,6 +89,15 @@ func makeslicecopy(et *_type, tolen int, fromlen int, from unsafe.Pointer) unsaf
        return to
 }
 
+// makeslice should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname makeslice
 func makeslice(et *_type, len, cap int) unsafe.Pointer {
        mem, overflow := math.MulUintptr(et.Size_, uintptr(cap))
        if overflow || mem > maxAlloc || len < 0 || len > cap {
@@ -156,6 +165,7 @@ func makeslice64(et *_type, len64, cap64 int64) unsafe.Pointer {
 // growslice should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
 //   - github.com/ugorji/go/codec
 //
 // Do not remove or change the type signature.
index 8196eb0c905afe74c52e66039007ff24c5027929..83f5e4e33087df6711c31430ef5cb33202f69f8c 100644 (file)
@@ -83,6 +83,15 @@ func badsystemstack() {
 //
 // The (CPU-specific) implementations of this function are in memclr_*.s.
 //
+// memclrNoHeapPointers should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname memclrNoHeapPointers
 //go:noescape
 func memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr)
 
@@ -108,6 +117,7 @@ func reflect_memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr) {
 // memmove should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
 //   - github.com/ugorji/go/codec
 //
 // Do not remove or change the type signature.
@@ -127,6 +137,15 @@ const hashLoad = float32(loadFactorNum) / float32(loadFactorDen)
 
 // in internal/bytealg/equal_*.s
 //
+// memequal should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname memequal
 //go:noescape
 func memequal(a, b unsafe.Pointer, size uintptr) bool
 
@@ -387,7 +406,18 @@ func abort()
 
 // Called from compiled code; declared for vet; do NOT call from Go.
 func gcWriteBarrier1()
+
+// gcWriteBarrier2 should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bytedance/sonic
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname gcWriteBarrier2
 func gcWriteBarrier2()
+
 func gcWriteBarrier3()
 func gcWriteBarrier4()
 func gcWriteBarrier5()