From bc2e961cf4cda945dc6d607a5076b4e376553e9f Mon Sep 17 00:00:00 2001
From: Carlo Alberto Ferraris <cafxx@strayorange.com>
Date: Thu, 21 Apr 2022 17:49:12 +0900
Subject: [PATCH] reflect: deprecate (Slice|String)Header

As discussed in CL 401434 there are substantial misuses of these in the
wild, and they are a potential source of unsafety even for code that
does not use them directly.

We should either keep them as-is and document when/how they can be used
safely, or deprecate them so that uses will eventually die out.

After some discussion, it was decided to deprecate them outright.
Since the docs already mentioned that they may be unstable across
releases, it should be possible to get rid of them completely later on.

Change-Id: I3b75819409177b5a286c1e9861a2edb6fd1301b8
Reviewed-on: https://go-review.googlesource.com/c/go/+/401434
Auto-Submit: Ian Lance Taylor <iant@google.com>
Run-TryBot: Ian Lance Taylor <iant@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
---
 doc/go1.19.html      | 10 ++++++++++
 src/reflect/value.go |  6 ++++++
 2 files changed, 16 insertions(+)

diff --git a/doc/go1.19.html b/doc/go1.19.html
index 164f967bdd..0bf5472246 100644
--- a/doc/go1.19.html
+++ b/doc/go1.19.html
@@ -166,6 +166,16 @@ Do not send CLs removing the interior tags from such phrases.
   </dd>
 </dl> <!-- os/exec -->
 
+<dl id="reflect"><dt><a href="/pkg/reflect/">reflect</a></dt>
+  <dd>
+    <p><!-- CL 401434 -->
+      <a href="/pkg/strconv/#reflect.SliceHeader"></a><code>reflect.SliceHeader</code>
+      and <a href="/pkg/strconv/#reflect.StringHeader"></a><code>reflect.StringHeader</code>
+      are now deprecated, and their use should be avoided.
+    </p>
+  </dd>
+</dl><!-- reflect -->
+
 <dl id="runtime"><dt><a href="/pkg/runtime/">runtime</a></dt>
   <dd>
     <p><!-- https://go.dev/issue/51461 -->
diff --git a/src/reflect/value.go b/src/reflect/value.go
index d68f7ad2e6..0fc19ef101 100644
--- a/src/reflect/value.go
+++ b/src/reflect/value.go
@@ -2660,6 +2660,9 @@ func (v Value) UnsafePointer() unsafe.Pointer {
 // Moreover, the Data field is not sufficient to guarantee the data
 // it references will not be garbage collected, so programs must keep
 // a separate, correctly typed pointer to the underlying data.
+//
+// Deprecated: this type should not be used, it exists only for
+// backward compatibility.
 type StringHeader struct {
 	Data uintptr
 	Len  int
@@ -2671,6 +2674,9 @@ type StringHeader struct {
 // Moreover, the Data field is not sufficient to guarantee the data
 // it references will not be garbage collected, so programs must keep
 // a separate, correctly typed pointer to the underlying data.
+//
+// Deprecated: this type should not be used, it exists only for
+// backward compatibility.
 type SliceHeader struct {
 	Data uintptr
 	Len  int
-- 
2.48.1