cralloc: add ScratchBuffer

Add a helper type for reusing a buffer. This simplifies the typical
pattern of passing and returning a slice. It is also useful for cases
where a function might return either a slice from the scratch buffer
or some other aliased slice (for example, `EncodeMVCCValueForExport`
in cockroachdb has to return an extra bool so the caller can know if
it should update the scratch buffer).

Author: RaduBerinde

cralloc/scratch_buffer.go

@@ -0,0 +1,100 @@
+// Copyright 2025 The Cockroach Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+// implied. See the License for the specific language governing
+// permissions and limitations under the License.
+
+package cralloc
+
+import "unsafe"
+
+// ScratchBuffer is a helper for the common pattern of reusing a byte buffer to
+// reduce slice allocations. To use, replace `make([]byte, n)` with
+// `sb.Alloc(n)`.
+type ScratchBuffer struct {
+	p        unsafe.Pointer
+	capacity int
+}
+
+// Alloc returns a byte slice of length n and arbitrary capacity which can be
+// used until the next call to Alloc.
+//
+// WARNING: the slice contains arbitrary data.
+//
+// If the receiver is nil, always allocates a new slice.
+func (sb *ScratchBuffer) Alloc(n int) []byte {
+	if sb == nil {
+		return make([]byte, n)
+	}
+	s := unsafe.Slice((*byte)(sb.p), sb.capacity)
+	if sb.capacity >= n {
+		return s[:n]
+	}
+	// Adapted from slices.Grow().
+	s = append(s[:0], make([]byte, n)...)
+	sb.p = unsafe.Pointer(&s[0])
+	sb.capacity = cap(s)
+	return s
+}
+
+// AllocZero returns a byte slice of length n and arbitrary capacity which can
+// be used until the next call to Alloc. The slice is zeroed out.
+//
+// WARNING: the slice contains arbitrary data between the length and the
+// capacity.
+//
+// If the receiver is nil, always allocates a new slice.
+func (sb *ScratchBuffer) AllocZero(n int) []byte {
+	if sb == nil {
+		return make([]byte, n)
+	}
+	s := unsafe.Slice((*byte)(sb.p), sb.capacity)
+	if sb.capacity >= n {
+		s = s[:n]
+		clear(s)
+		return s
+	}
+	// Adapted from slices.Grow().
+	s = append(s[:0], make([]byte, n)...)
+	sb.p = unsafe.Pointer(&s[0])
+	sb.capacity = cap(s)
+	return s
+}
+
+// Append is like the built-in append(), but it also updates the scratch buffer
+// so that any newly allocated buffer can be reused.
+//
+// Append can be used with buffers not allocated through the scratch buffer (in
+// which case the scratch buffer is not updated).
+func (sb *ScratchBuffer) Append(buf []byte, values ...byte) []byte {
+	res := append(buf, values...)
+	if sb != nil && unsafe.SliceData(buf) == (*byte)(sb.p) && unsafe.SliceData(res) != (*byte)(sb.p) {
+		sb.p = unsafe.Pointer(unsafe.SliceData(res))
+		sb.capacity = cap(res)
+	}
+	return res
+}
+
+// Capacity returns the current capacity.
+func (sb *ScratchBuffer) Capacity() int {
+	if sb == nil {
+		return 0
+	}
+	return sb.capacity
+}
+
+// Reset clears the buffer. This can be useful if we want to avoid retaining a
+// very large buffer.
+func (sb *ScratchBuffer) Reset() {
+	if sb != nil {
+		*sb = ScratchBuffer{}
+	}
+}

cralloc/scratch_buffer_test.go

@@ -0,0 +1,71 @@
+// Copyright 2025 The Cockroach Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+// implied. See the License for the specific language governing
+// permissions and limitations under the License.
+
+package cralloc
+
+import (
+	"math/rand/v2"
+	"testing"
+
+	"github.com/cockroachdb/crlib/testutils/require"
+)
+
+func TestScratchBuffer(t *testing.T) {
+	s := (*ScratchBuffer)(nil).Alloc(100)
+	require.Equal(t, len(s), 100)
+	var sb ScratchBuffer
+	s = sb.Alloc(100)
+	require.Equal(t, len(s), 100)
+	c := cap(s)
+	s = sb.Alloc(50)
+	require.Equal(t, len(s), 50)
+	require.Equal(t, cap(s), c)
+	s = sb.Alloc(101)
+	require.Equal(t, len(s), 101)
+	require.GT(t, cap(s), 101)
+
+	t.Run("AllocZero", func(t *testing.T) {
+		for range 100 {
+			var sb ScratchBuffer
+			maxN := 1 + rand.IntN(1000)
+			for range 20 {
+				n := rand.IntN(maxN)
+				b := sb.AllocZero(n)
+				for i := range b {
+					require.Equal(t, b[i], 0)
+				}
+				// Trash the entire buffer.
+				b = b[:cap(b)]
+				for i := range b {
+					b[i] = 0xcc
+				}
+			}
+		}
+	})
+
+	t.Run("Append", func(t *testing.T) {
+		var sb ScratchBuffer
+		b := sb.Alloc(100)
+		b = sb.Append(b, make([]byte, 1000)...)
+		require.Equal(t, len(b), 1100)
+		// Ensure the capacity has grown.
+		require.GE(t, sb.Capacity(), 1100)
+
+		// Append an unrelated slice.
+		b = sb.Append(make([]byte, 1100), make([]byte, 10000)...)
+		require.Equal(t, len(b), 11100)
+		// Ensure the capacity did not grow.
+		require.LT(t, sb.Capacity(), 10000)
+	})
+}