weak: move internal/weak to weak, and update according to proposal

The updates are:
- API documentation changes.
- Removal of the old package documentation discouraging linkname.
- Addition of new package documentation with some advice.
- Renaming of weak.Pointer.Strong -> weak.Pointer.Value.

Fixes #67552.

Change-Id: Ifad7e629b6d339dacaf2ca37b459d7f903e31bf8
Reviewed-on: https://go-review.googlesource.com/c/go/+/628455
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Carlos Amedee <carlos@golang.org>
Auto-Submit: Michael Knyszek <mknyszek@google.com>

3 files changed, 6 insertions, 6 deletions

diff --git a/src/runtime/gc_test.go b/src/runtime/gc_test.go
index 35ddfeadc1..35cb634936 100644
--- a/src/runtime/gc_test.go
+++ b/src/runtime/gc_test.go
@@ -8,7 +8,6 @@ import (
 	"fmt"
 	"internal/asan"
 	"internal/testenv"
-	"internal/weak"
 	"math/bits"
 	"math/rand"
 	"os"
@@ -22,6 +21,7 @@ import (
 	"testing"
 	"time"
 	"unsafe"
+	"weak"
 )
 
 func TestGcSys(t *testing.T) {
@@ -826,7 +826,7 @@ func TestWeakToStrongMarkTermination(t *testing.T) {
 
 	// Start a GC, and wait a little bit to get something spinning in mark termination.
 	// Simultaneously, fire off another goroutine to disable spinning. If everything's
-	// working correctly, then weak.Strong will block, so we need to make sure something
+	// working correctly, then weak.Value will block, so we need to make sure something
 	// prevents the GC from continuing to spin.
 	done := make(chan struct{})
 	go func() {
@@ -847,7 +847,7 @@ func TestWeakToStrongMarkTermination(t *testing.T) {
 		wg.Add(1)
 		go func() {
 			defer wg.Done()
-			wp.Strong()
+			wp.Value()
 		}()
 	}
 
diff --git a/src/runtime/mgcsweep.go b/src/runtime/mgcsweep.go
index eb6d985ce0..b6890bac47 100644
--- a/src/runtime/mgcsweep.go
+++ b/src/runtime/mgcsweep.go
@@ -564,7 +564,7 @@ func (sl *sweepLocked) sweep(preserve bool) bool {
 			}
 			if hasFinAndRevived {
 				// Pass 2: queue all finalizers and clear any weak handles. Weak handles are cleared
-				// before finalization as specified by the internal/weak package. See the documentation
+				// before finalization as specified by the weak package. See the documentation
 				// for that package for more details.
 				for siter.valid() && uintptr(siter.s.offset) < endOffset {
 					// Find the exact byte for which the special was setup
diff --git a/src/runtime/mheap.go b/src/runtime/mheap.go
index 031c7ee9c3..47b2d6f40a 100644
--- a/src/runtime/mheap.go
+++ b/src/runtime/mheap.go
@@ -2092,12 +2092,12 @@ type specialWeakHandle struct {
 	handle *atomic.Uintptr
 }
 
-//go:linkname internal_weak_runtime_registerWeakPointer internal/weak.runtime_registerWeakPointer
+//go:linkname internal_weak_runtime_registerWeakPointer weak.runtime_registerWeakPointer
 func internal_weak_runtime_registerWeakPointer(p unsafe.Pointer) unsafe.Pointer {
 	return unsafe.Pointer(getOrAddWeakHandle(unsafe.Pointer(p)))
 }
 
-//go:linkname internal_weak_runtime_makeStrongFromWeak internal/weak.runtime_makeStrongFromWeak
+//go:linkname internal_weak_runtime_makeStrongFromWeak weak.runtime_makeStrongFromWeak
 func internal_weak_runtime_makeStrongFromWeak(u unsafe.Pointer) unsafe.Pointer {
 	handle := (*atomic.Uintptr)(u)