From e3b15b0ebae51fa744018b480af2c96096c03e64 Mon Sep 17 00:00:00 2001 From: Josue Giron Date: Sat, 21 Nov 2026 20:20:46 +0000 Subject: [PATCH 1/3] test(async): add container get benchmarks Co-Authored-By: Claude Opus 5.5 --- async/async_container_bench_test.go | 60 +++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 async/async_container_bench_test.go diff --git a/async/async_container_bench_test.go b/async/async_container_bench_test.go new file mode 100644 index 0000000..f7d6671 --- /dev/null +++ b/async/async_container_bench_test.go @@ -0,0 +1,60 @@ +package async + +import ( + "strconv" + "testing" +) + +type benchFlatStruct struct { + ID int + Name string + Score float64 +} + +type benchNestedStruct struct { + Name string + Tags []string + Attrs map[string]int + Parent *benchFlatStruct +} + +func BenchmarkContainerGet(b *testing.B) { + attrs := make(map[string]int, 100) + for i := 0; i < 100; i++ { + attrs[strconv.Itoa(i)] = i + } + + b.Run("int", func(b *testing.B) { + benchmarkGet[int](b, 42) + }) + b.Run("flat_struct", func(b *testing.B) { + benchmarkGet[benchFlatStruct](b, benchFlatStruct{ID: 1, Name: "alice", Score: 9.5}) + }) + b.Run("slice_1k_int", func(b *testing.B) { + benchmarkGet[[]int](b, make([]int, 1000)) + }) + b.Run("map_100", func(b *testing.B) { + benchmarkGet[map[string]int](b, attrs) + }) + b.Run("nested_struct", func(b *testing.B) { + benchmarkGet[benchNestedStruct](b, benchNestedStruct{ + Name: "node", + Tags: []string{"a", "b", "c"}, + Attrs: map[string]int{"x": 1, "y": 2}, + Parent: &benchFlatStruct{ID: 1, Name: "root"}, + }) + }) +} + +func benchmarkGet[T any](b *testing.B, stored T) { + container := &Container{} + container.Set("key", stored, nil) + var got T + + b.ReportAllocs() + for b.Loop() { + if err := container.Get("key", &got); err != nil { + b.Fatal(err) + } + } +} From 8cceb9bf189acf3fcf5f5c90952c8b0824ec1423 Mon Sep 17 00:00:00 2001 From: Josue Giron Date: Sat, 21 Nov 2026 20:25:33 +0000 Subject: [PATCH 2/3] fix(async)!: return a deep copy from container get Get handed back the stored slice, map or pointer itself, so every caller shared it with the container and with each other, and writes to what Get returned raced. Get now deep-copies the stored value before the assign and convert paths. BREAKING CHANGE: Container.Get returns a deep copy of the stored value instead of sharing slices, maps and pointed-to data. Unexported struct fields are copied shallowly; map keys, channels, functions and unsafe pointers stay shared. Co-Authored-By: Claude Opus 5.5 --- README.md | 3 + async/async_container.go | 20 ++- async/async_container_test.go | 273 ++++++++++++++++++++++++++++++++++ async/deep_copy.go | 172 +++++++++++++++++++++ async/deep_copy_test.go | 195 ++++++++++++++++++++++++ async/doc.go | 2 + 6 files changed, 661 insertions(+), 4 deletions(-) create mode 100644 async/deep_copy.go create mode 100644 async/deep_copy_test.go diff --git a/README.md b/README.md index c72604d..495ef25 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,8 @@ if err := c.TrySet("job", result, nil); err != nil { `Set` panics when the key is `nil` or not comparable, similar to how an invalid insertion into a regular `map` would fail at runtime. +`Get` returns a deep copy of the stored value, so goroutines can modify what they receive without racing; unexported struct fields are copied shallowly, and map keys, channels and functions are shared. Do not modify a value after storing it. + ### `txml` Normalize first when the payload is escaped or declares a Latin-1 header: @@ -77,6 +79,7 @@ Recent changes to consider if the library already has consumers: - `info.Info.Get` returns `nil` when the map itself is `nil`. - `info.Info` now provides `Lookup*` helpers for explicit contracts. - `async.Container` now exposes `TrySet` to avoid panics on invalid keys. +- `async.Container.Get` returns a deep copy of the stored value (v0.2.0); before, slices, maps and pointers were shared between the container and every caller. - `async.Container.Get` quotes the key in its not-found error (`key ("missing")`), so control characters in untrusted keys are escaped. - `txml.XMLString.Decode` now decodes directly into the caller-provided destination pointer. diff --git a/async/async_container.go b/async/async_container.go index 7e95d50..1087f1b 100644 --- a/async/async_container.go +++ b/async/async_container.go @@ -15,6 +15,8 @@ type Container struct { } // Set stores a value and optional error for a key. +// The container keeps value as given, so the caller must not modify it after +// storing it. // It panics if the key is nil or not comparable; prefer TrySet when the key is not trusted. func (c *Container) Set(key interface{}, value interface{}, err error) { if err := c.TrySet(key, value, err); err != nil { @@ -23,6 +25,8 @@ func (c *Container) Set(key interface{}, value interface{}, err error) { } // TrySet stores a value and optional error for a key and returns validation errors. +// The container keeps value as given, so the caller must not modify it after +// storing it. func (c *Container) TrySet(key interface{}, value interface{}, err error) error { if err := validateKey(key); err != nil { return err @@ -46,8 +50,16 @@ func (c *Container) TrySet(key interface{}, value interface{}, err error) error return nil } -// Get copies the stored value into value and returns any error associated with the key. -// value must be a non-nil pointer. +// Get stores a deep copy of the value stored for key into value and returns +// any error associated with the key. value must be a non-nil pointer. +// +// The copy shares no pointed-to, slice, or map data with the stored value or +// with other callers, so callers may modify what they receive. Limits: +// - unexported struct fields are copied shallowly, so data they reference +// stays shared; +// - map keys, channels, functions, and unsafe pointers are shared; +// - when the stored value is neither assignable nor convertible to the +// type value points to, it is decoded through a JSON round trip instead. func (c *Container) Get(key interface{}, value interface{}) error { if err := validateKey(key); err != nil { return err @@ -111,7 +123,7 @@ func assignValue(dst interface{}, src interface{}) error { srcValue := reflect.ValueOf(src) if srcValue.Type().AssignableTo(dstElem.Type()) { - dstElem.Set(srcValue) + dstElem.Set(deepCopy(srcValue)) return nil } @@ -119,7 +131,7 @@ func assignValue(dst interface{}, src interface{}) error { if err := checkSliceToArrayLength(srcValue, dstElem.Type()); err != nil { return err } - dstElem.Set(srcValue.Convert(dstElem.Type())) + dstElem.Set(deepCopy(srcValue).Convert(dstElem.Type())) return nil } diff --git a/async/async_container_test.go b/async/async_container_test.go index 04a14b5..a0a383e 100644 --- a/async/async_container_test.go +++ b/async/async_container_test.go @@ -2,6 +2,8 @@ package async import ( "errors" + "reflect" + "sync" "testing" ) @@ -268,3 +270,274 @@ func TestContainerGetMissingKeyQuotesKey(t *testing.T) { }) } } + +func TestContainerGetConcurrentSliceWritesDoNotRace(t *testing.T) { + container := &Container{} + container.Set("numbers", []int{0}, nil) + + var wg sync.WaitGroup + for writer := 1; writer <= 2; writer++ { + wg.Add(1) + go func() { + defer wg.Done() + var got []int + if err := container.Get("numbers", &got); err != nil { + t.Errorf("Get() error = %v", err) + return + } + got[0] = writer + }() + } + wg.Wait() + + var got []int + if err := container.Get("numbers", &got); err != nil { + t.Fatalf("Get() error = %v", err) + } + if !reflect.DeepEqual(got, []int{0}) { + t.Fatalf("Get() = %v, want [0]", got) + } +} + +func TestContainerGetConcurrentMapWritesDoNotRace(t *testing.T) { + container := &Container{} + container.Set("groups", map[string][]int{"a": {0}}, nil) + + var wg sync.WaitGroup + for writer := 1; writer <= 2; writer++ { + wg.Add(1) + go func() { + defer wg.Done() + var got map[string][]int + if err := container.Get("groups", &got); err != nil { + t.Errorf("Get() error = %v", err) + return + } + got["b"] = []int{writer} + got["a"][0] = writer + }() + } + wg.Wait() + + var got map[string][]int + if err := container.Get("groups", &got); err != nil { + t.Fatalf("Get() error = %v", err) + } + if want := map[string][]int{"a": {0}}; !reflect.DeepEqual(got, want) { + t.Fatalf("Get() = %v, want %v", got, want) + } +} + +type copyTarget struct { + Name string + Items []int + Attrs map[string]int + Parent *copyTarget +} + +type copyIDs []int + +// getAndMutate reads key into a fresh T and mutates what it received. +func getAndMutate[T any](mutate func(got *T)) func(c *Container) error { + return func(c *Container) error { + var got T + if err := c.Get("key", &got); err != nil { + return err + } + mutate(&got) + return nil + } +} + +func TestContainerGetResultIsIndependentOfStoredValue(t *testing.T) { + tests := []struct { + name string + // build returns a fresh copy of the stored value on every call, so + // one copy is stored and another is the expected content. + build func() interface{} + getMutate func(c *Container) error + }{ + { + name: "slice", + build: func() interface{} { return []int{1, 2, 3} }, + getMutate: getAndMutate(func(got *[]int) { + (*got)[0] = 9 + }), + }, + { + name: "map of slices", + build: func() interface{} { return map[string][]int{"a": {1}} }, + getMutate: getAndMutate(func(got *map[string][]int) { + (*got)["a"][0] = 9 + (*got)["b"] = []int{2} + }), + }, + { + name: "pointer to struct", + build: func() interface{} { + return ©Target{Name: "n", Items: []int{1}, Attrs: map[string]int{"a": 1}, Parent: ©Target{Name: "p"}} + }, + getMutate: getAndMutate(func(got **copyTarget) { + (*got).Name = "changed" + (*got).Items[0] = 9 + (*got).Attrs["a"] = 9 + (*got).Parent.Name = "changed" + }), + }, + { + name: "struct with reference fields", + build: func() interface{} { + return copyTarget{Items: []int{1}, Attrs: map[string]int{"a": 1}, Parent: ©Target{Name: "p"}} + }, + getMutate: getAndMutate(func(got *copyTarget) { + got.Items[0] = 9 + got.Attrs["a"] = 9 + got.Parent.Name = "changed" + }), + }, + { + name: "slice of interfaces into interface", + build: func() interface{} { return []interface{}{[]int{1}, map[string]interface{}{"a": 1}} }, + getMutate: getAndMutate(func(got *interface{}) { + values := (*got).([]interface{}) + values[0].([]int)[0] = 9 + values[1].(map[string]interface{})["a"] = 9 + }), + }, + { + name: "map of interfaces into concrete type", + build: func() interface{} { return map[string]interface{}{"list": []interface{}{1, "x"}} }, + getMutate: getAndMutate(func(got *map[string]interface{}) { + (*got)["list"].([]interface{})[0] = 9 + (*got)["new"] = true + }), + }, + { + name: "named slice converted to slice", + build: func() interface{} { return copyIDs{1, 2} }, + getMutate: getAndMutate(func(got *[]int) { + (*got)[0] = 9 + }), + }, + { + name: "slice converted to array pointer", + build: func() interface{} { return []int{1, 2, 3, 4, 5} }, + getMutate: getAndMutate(func(got **[4]int) { + (*got)[0] = 9 + }), + }, + { + name: "nil references stay nil", + build: func() interface{} { return []interface{}{nil, copyTarget{}, []int(nil), map[string]int(nil)} }, + getMutate: getAndMutate(func(got *[]interface{}) { + (*got)[0] = 9 + }), + }, + { + name: "int", + build: func() interface{} { return 42 }, + getMutate: getAndMutate(func(got *int) { + *got = 9 + }), + }, + { + name: "string", + build: func() interface{} { return "value" }, + getMutate: getAndMutate(func(got *string) { + *got = "changed" + }), + }, + { + name: "flat struct", + build: func() interface{} { return struct{ A, B int }{1, 2} }, + getMutate: getAndMutate(func(got *struct{ A, B int }) { + got.A = 9 + }), + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + container := &Container{} + container.Set("key", tt.build(), nil) + want := tt.build() + + if err := tt.getMutate(container); err != nil { + t.Fatalf("Get() error = %v", err) + } + var got interface{} + if err := container.Get("key", &got); err != nil { + t.Fatalf("second Get() error = %v", err) + } + + if !reflect.DeepEqual(got, want) { + t.Fatalf("second Get() = %#v, want %#v", got, want) + } + }) + } +} + +type cyclicNode struct { + Name string + Next *cyclicNode +} + +func TestContainerGetCopiesSelfReferencingPointer(t *testing.T) { + stored := &cyclicNode{Name: "loop"} + stored.Next = stored + container := &Container{} + container.Set("key", stored, nil) + + var got *cyclicNode + err := container.Get("key", &got) + + if err != nil { + t.Fatalf("Get() error = %v", err) + } + if got == stored || got.Next != got || got.Name != "loop" { + t.Fatalf("Get() = %p (next %p), stored %p; want a new self-referencing node", got, got.Next, stored) + } +} + +func TestContainerGetCopiesSelfReferencingSlice(t *testing.T) { + stored := make([]interface{}, 1) + stored[0] = stored + container := &Container{} + container.Set("key", stored, nil) + + var got []interface{} + err := container.Get("key", &got) + + if err != nil { + t.Fatalf("Get() error = %v", err) + } + inner := got[0].([]interface{}) + if &got[0] == &stored[0] || &inner[0] != &got[0] { + t.Fatalf("Get() did not return a new self-referencing slice") + } +} + +func TestContainerGetStructWithUnexportedField(t *testing.T) { + type withHidden struct { + Name string + Items []int + items []int + } + stored := withHidden{Name: "n", Items: []int{1}, items: []int{2}} + container := &Container{} + container.Set("key", stored, nil) + + var got withHidden + err := container.Get("key", &got) + + if err != nil { + t.Fatalf("Get() error = %v", err) + } + if got.Name != "n" || &got.Items[0] == &stored.Items[0] { + t.Fatalf("Get() = %+v; want exported fields deep-copied", got) + } + // Unexported fields cannot be set through reflect, so they stay shared. + if &got.items[0] != &stored.items[0] { + t.Fatalf("Get() copied the unexported field; documented as shared") + } +} diff --git a/async/deep_copy.go b/async/deep_copy.go new file mode 100644 index 0000000..291431d --- /dev/null +++ b/async/deep_copy.go @@ -0,0 +1,172 @@ +package async + +import "reflect" + +// copier deep-copies one value. Its memo maps every pointer, map, and slice +// already copied to its copy, so shared and self-referencing data keep their +// shape in the copy and the copy terminates on cycles. +type copier struct { + memo map[referenceKey]reflect.Value +} + +// referenceKey identifies a pointer, map, or slice header. Slices also carry +// len and cap, because two slices over the same array can differ in both. +type referenceKey struct { + typ reflect.Type + address uintptr + length int + capacity int +} + +// deepCopy returns a copy of v that shares no pointed-to, slice, or map data +// with v. Unexported struct fields are copied shallowly, because reflect +// cannot set them without unsafe; map keys, channels, functions, and unsafe +// pointers are shared. +func deepCopy(v reflect.Value) reflect.Value { + if !hasReferences(v.Type()) { + return v + } + + c := copier{memo: map[referenceKey]reflect.Value{}} + return c.copy(v) +} + +// hasReferences reports whether a value of type t can reach data that a +// deep copy must duplicate. +func hasReferences(t reflect.Type) bool { + switch t.Kind() { + case reflect.Pointer, reflect.Slice, reflect.Map, reflect.Interface: + return true + case reflect.Array: + return hasReferences(t.Elem()) + case reflect.Struct: + for i := 0; i < t.NumField(); i++ { + if hasReferences(t.Field(i).Type) { + return true + } + } + return false + default: + return false + } +} + +func (c *copier) copy(v reflect.Value) reflect.Value { + switch v.Kind() { + case reflect.Pointer: + return c.copyPointer(v) + case reflect.Slice: + return c.copySlice(v) + case reflect.Map: + return c.copyMap(v) + case reflect.Array: + return c.copyArray(v) + case reflect.Struct: + return c.copyStruct(v) + case reflect.Interface: + return c.copyInterface(v) + default: + return v + } +} + +func (c *copier) copyPointer(v reflect.Value) reflect.Value { + if v.IsNil() { + return v + } + + key := referenceKey{typ: v.Type(), address: v.Pointer()} + if copied, ok := c.memo[key]; ok { + return copied + } + + out := reflect.New(v.Type().Elem()) + c.memo[key] = out + out.Elem().Set(c.copy(v.Elem())) + return out +} + +func (c *copier) copySlice(v reflect.Value) reflect.Value { + if v.IsNil() { + return v + } + + key := referenceKey{typ: v.Type(), address: v.Pointer(), length: v.Len(), capacity: v.Cap()} + if copied, ok := c.memo[key]; ok { + return copied + } + + out := reflect.MakeSlice(v.Type(), v.Len(), v.Len()) + c.memo[key] = out + if !hasReferences(v.Type().Elem()) { + reflect.Copy(out, v) + return out + } + + for i := 0; i < v.Len(); i++ { + out.Index(i).Set(c.copy(v.Index(i))) + } + return out +} + +func (c *copier) copyMap(v reflect.Value) reflect.Value { + if v.IsNil() { + return v + } + + key := referenceKey{typ: v.Type(), address: v.Pointer()} + if copied, ok := c.memo[key]; ok { + return copied + } + + out := reflect.MakeMapWithSize(v.Type(), v.Len()) + c.memo[key] = out + // Reusing one key and one value holder avoids an allocation per entry + // that MapRange's Key and Value would make. + entryKey := reflect.New(v.Type().Key()).Elem() + entryValue := reflect.New(v.Type().Elem()).Elem() + entries := v.MapRange() + for entries.Next() { + entryKey.SetIterKey(entries) + entryValue.SetIterValue(entries) + out.SetMapIndex(entryKey, c.copy(entryValue)) + } + return out +} + +func (c *copier) copyArray(v reflect.Value) reflect.Value { + if !hasReferences(v.Type().Elem()) { + return v + } + + out := reflect.New(v.Type()).Elem() + for i := 0; i < v.Len(); i++ { + out.Index(i).Set(c.copy(v.Index(i))) + } + return out +} + +// copyStruct sets the whole struct first so unexported fields keep their +// (shared) value, then replaces only the fields reflect allows to set. +// Values read from unexported fields are never passed to Set, which would +// panic. +func (c *copier) copyStruct(v reflect.Value) reflect.Value { + out := reflect.New(v.Type()).Elem() + out.Set(v) + for i := 0; i < v.NumField(); i++ { + if field := out.Field(i); field.CanSet() { + field.Set(c.copy(v.Field(i))) + } + } + return out +} + +func (c *copier) copyInterface(v reflect.Value) reflect.Value { + if v.IsNil() { + return v + } + + out := reflect.New(v.Type()).Elem() + out.Set(c.copy(v.Elem())) + return out +} diff --git a/async/deep_copy_test.go b/async/deep_copy_test.go new file mode 100644 index 0000000..9d37f5c --- /dev/null +++ b/async/deep_copy_test.go @@ -0,0 +1,195 @@ +package async + +import ( + "reflect" + "testing" +) + +func copyOf[T any](value T) T { + return deepCopy(reflect.ValueOf(value)).Interface().(T) +} + +func TestDeepCopyKeepsContent(t *testing.T) { + type nested struct { + Items []int + Attrs map[string][]string + Parent *nested + Any interface{} + Fixed [2][]int + } + tests := []struct { + name string + value interface{} + }{ + {name: "int", value: 7}, + {name: "string", value: "text"}, + {name: "slice", value: []int{1, 2, 3}}, + {name: "empty slice", value: []int{}}, + {name: "map", value: map[string]int{"a": 1}}, + {name: "array of slices", value: [2][]int{{1}, {2}}}, + {name: "pointer", value: &nested{Items: []int{1}}}, + { + name: "nested struct", + value: nested{ + Items: []int{1}, + Attrs: map[string][]string{"a": {"x"}}, + Parent: &nested{Any: []interface{}{1, "y"}}, + Any: map[string]interface{}{"k": []int{2}}, + Fixed: [2][]int{{3}, nil}, + }, + }, + {name: "nil slice", value: []int(nil)}, + {name: "nil map", value: map[string]int(nil)}, + {name: "nil pointer", value: (*nested)(nil)}, + {name: "nil interface element", value: []interface{}{nil}}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := copyOf(tt.value) + + if !reflect.DeepEqual(got, tt.value) { + t.Fatalf("deepCopy() = %#v, want %#v", got, tt.value) + } + }) + } +} + +func TestDeepCopySliceHasOwnBackingArray(t *testing.T) { + backing := []int{1, 2, 3, 4} + original := backing[:2] + + got := copyOf(original) + + if &got[0] == &original[0] { + t.Fatalf("deepCopy() shares the backing array") + } + if len(got) != 2 || cap(got) != 2 { + t.Fatalf("deepCopy() len/cap = %d/%d, want 2/2", len(got), cap(got)) + } +} + +func TestDeepCopyMapHasOwnStorage(t *testing.T) { + original := map[string][]int{"a": {1}} + + got := copyOf(original) + got["a"][0] = 9 + got["b"] = nil + + if original["a"][0] != 1 || len(original) != 1 { + t.Fatalf("deepCopy() result aliases the original: %v", original) + } +} + +func TestDeepCopyPointerHasNewPointee(t *testing.T) { + type box struct{ Items []int } + original := &box{Items: []int{1}} + + got := copyOf(original) + + if got == original || &got.Items[0] == &original.Items[0] { + t.Fatalf("deepCopy() shares the pointee") + } +} + +func TestDeepCopyInterfaceKeepsDynamicType(t *testing.T) { + original := []interface{}{copyIDs{1}, map[string]int{"a": 1}} + + got := copyOf(original) + + ids, ok := got[0].(copyIDs) + if !ok { + t.Fatalf("deepCopy() element type = %T, want copyIDs", got[0]) + } + if &ids[0] == &original[0].(copyIDs)[0] { + t.Fatalf("deepCopy() shares the slice held by the interface") + } +} + +func TestDeepCopyKeepsSharedReferencesShared(t *testing.T) { + type pair struct{ A, B *int } + shared := 1 + original := pair{A: &shared, B: &shared} + + got := copyOf(original) + + if got.A != got.B || got.A == &shared { + t.Fatalf("deepCopy() = %p/%p, want one new shared pointer", got.A, got.B) + } +} + +func TestDeepCopySelfReferencingMap(t *testing.T) { + original := map[string]interface{}{} + original["self"] = original + + got := copyOf(original) + + inner := got["self"].(map[string]interface{}) + inner["added"] = true + if _, ok := got["added"]; !ok { + t.Fatalf("deepCopy() did not keep the cycle in the copy") + } + if _, ok := original["added"]; ok { + t.Fatalf("deepCopy() result aliases the original") + } +} + +func TestDeepCopySharesUncopyableKinds(t *testing.T) { + type holder struct { + Events chan int + Run func() int + } + original := holder{Events: make(chan int), Run: func() int { return 1 }} + + got := copyOf(original) + + if got.Events != original.Events || got.Run() != 1 { + t.Fatalf("deepCopy() did not keep the channel and function") + } +} + +func TestDeepCopyUnexportedFieldIsShallow(t *testing.T) { + type hidden struct { + Visible []int + hidden []int + } + original := hidden{Visible: []int{1}, hidden: []int{2}} + + got := copyOf(original) + + if &got.Visible[0] == &original.Visible[0] { + t.Fatalf("deepCopy() shares the exported field") + } + if &got.hidden[0] != &original.hidden[0] { + t.Fatalf("deepCopy() copied the unexported field; documented as shared") + } +} + +func TestHasReferences(t *testing.T) { + tests := []struct { + name string + value interface{} + want bool + }{ + {name: "int", value: 1, want: false}, + {name: "string", value: "s", want: false}, + {name: "flat struct", value: struct{ A, B int }{}, want: false}, + {name: "array of ints", value: [3]int{}, want: false}, + {name: "channel", value: make(chan int), want: false}, + {name: "slice", value: []int{}, want: true}, + {name: "pointer", value: new(int), want: true}, + {name: "map", value: map[int]int{}, want: true}, + {name: "array of interfaces", value: [1]interface{}{}, want: true}, + {name: "struct with nested slice", value: struct{ Inner struct{ S []int } }{}, want: true}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := hasReferences(reflect.TypeOf(tt.value)) + + if got != tt.want { + t.Fatalf("hasReferences(%T) = %v, want %v", tt.value, got, tt.want) + } + }) + } +} diff --git a/async/doc.go b/async/doc.go index 8992f4f..5f6776c 100644 --- a/async/doc.go +++ b/async/doc.go @@ -5,4 +5,6 @@ // use: producers store results with [Container.Set] or [Container.TrySet], and // consumers read them back with [Container.Get]. Use TrySet when the key comes // from untrusted input, since Set panics on a nil or non-comparable key. +// Get returns a deep copy of the stored value, so consumers may modify what +// they receive; see [Container.Get] for the limits. package async From defb2018c717d1fe2a6a095f07c9f1bda097b4fa Mon Sep 17 00:00:00 2001 From: Josue Giron Date: Sat, 21 Nov 2026 20:29:46 +0000 Subject: [PATCH 3/3] fix(async): share pointers to structs with unexported fields Copying the pointee of types such as *strings.Builder or *bytes.Buffer breaks or duplicates their internal state, so such pointers are now shared as-is. Get copies outside the read lock so writers do not wait on a copy. Document the limits in the README and record the decision in ADR 0001. Co-Authored-By: Claude Opus 5.5 --- README.md | 7 +++- async/async_container.go | 20 ++++++----- async/async_container_test.go | 52 ++++++++++++++++++++++------ async/deep_copy.go | 23 ++++++++++-- async/deep_copy_test.go | 42 ++++++++++++++++++---- docs/adr/0001-async-get-deep-copy.md | 28 +++++++++++++++ 6 files changed, 144 insertions(+), 28 deletions(-) create mode 100644 docs/adr/0001-async-get-deep-copy.md diff --git a/README.md b/README.md index 495ef25..9eef96d 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,12 @@ if err := c.TrySet("job", result, nil); err != nil { `Set` panics when the key is `nil` or not comparable, similar to how an invalid insertion into a regular `map` would fail at runtime. -`Get` returns a deep copy of the stored value, so goroutines can modify what they receive without racing; unexported struct fields are copied shallowly, and map keys, channels and functions are shared. Do not modify a value after storing it. +`Get` returns a deep copy of the stored value, so goroutines can modify what they receive without racing. Do not modify a value after storing it. Limits of the copy: + +- unexported struct fields are copied shallowly, including exported fields promoted from an embedded unexported struct (the embedded field itself is unexported); +- pointers to structs with unexported fields are shared as-is, since such types usually own internal state (locks, buffers) that a copy would break; +- map keys, channels, functions and unsafe pointers are shared; +- when the stored value is neither assignable nor convertible to the destination type, it is decoded through a JSON round trip instead. ### `txml` diff --git a/async/async_container.go b/async/async_container.go index 1087f1b..164f8ac 100644 --- a/async/async_container.go +++ b/async/async_container.go @@ -56,7 +56,11 @@ func (c *Container) TrySet(key interface{}, value interface{}, err error) error // The copy shares no pointed-to, slice, or map data with the stored value or // with other callers, so callers may modify what they receive. Limits: // - unexported struct fields are copied shallowly, so data they reference -// stays shared; +// stays shared; this includes exported fields promoted from an embedded +// unexported struct, since the embedded field itself is unexported; +// - pointers to structs with unexported fields are shared as-is, since such +// types usually own internal state (locks, buffers) that a copy would +// break; // - map keys, channels, functions, and unsafe pointers are shared; // - when the stored value is neither assignable nor convertible to the // type value points to, it is decoded through a JSON round trip instead. @@ -66,22 +70,22 @@ func (c *Container) Get(key interface{}, value interface{}) error { } c.mu.RLock() - defer c.mu.RUnlock() - content, ok := c.content[key] + storedErr := c.errors[key] + c.mu.RUnlock() + if !ok { return notFoundError(key) } + // The copy runs outside the lock so that a slow copy does not block + // writers; this is safe because the container never mutates a stored + // value, it only replaces map entries. if err := assignValue(value, content); err != nil { return err } - if c.errors != nil && c.errors[key] != nil { - return c.errors[key] - } - - return nil + return storedErr } // notFoundError quotes the key so that a key from untrusted input cannot diff --git a/async/async_container_test.go b/async/async_container_test.go index a0a383e..b1a89dd 100644 --- a/async/async_container_test.go +++ b/async/async_container_test.go @@ -3,6 +3,7 @@ package async import ( "errors" "reflect" + "strings" "sync" "testing" ) @@ -517,27 +518,58 @@ func TestContainerGetCopiesSelfReferencingSlice(t *testing.T) { } } -func TestContainerGetStructWithUnexportedField(t *testing.T) { - type withHidden struct { - Name string - Items []int - items []int - } - stored := withHidden{Name: "n", Items: []int{1}, items: []int{2}} +type withHidden struct { + Name string + Items []int + items []int +} + +func getWithHidden(t *testing.T, stored withHidden) withHidden { + t.Helper() container := &Container{} container.Set("key", stored, nil) var got withHidden - err := container.Get("key", &got) - - if err != nil { + if err := container.Get("key", &got); err != nil { t.Fatalf("Get() error = %v", err) } + return got +} + +func TestContainerGetStructDeepCopiesExportedFields(t *testing.T) { + stored := withHidden{Name: "n", Items: []int{1}, items: []int{2}} + + got := getWithHidden(t, stored) + if got.Name != "n" || &got.Items[0] == &stored.Items[0] { t.Fatalf("Get() = %+v; want exported fields deep-copied", got) } +} + +func TestContainerGetStructSharesUnexportedFields(t *testing.T) { + stored := withHidden{Name: "n", Items: []int{1}, items: []int{2}} + + got := getWithHidden(t, stored) + // Unexported fields cannot be set through reflect, so they stay shared. if &got.items[0] != &stored.items[0] { t.Fatalf("Get() copied the unexported field; documented as shared") } } + +func TestContainerGetSharesPointerToStructWithUnexportedFields(t *testing.T) { + stored := &strings.Builder{} + stored.WriteString("a") + container := &Container{} + container.Set("key", stored, nil) + + var got *strings.Builder + if err := container.Get("key", &got); err != nil { + t.Fatalf("Get() error = %v", err) + } + got.WriteString("b") + + if got != stored { + t.Fatalf("Get() = %p, want the stored pointer %p", got, stored) + } +} diff --git a/async/deep_copy.go b/async/deep_copy.go index 291431d..e431cb1 100644 --- a/async/deep_copy.go +++ b/async/deep_copy.go @@ -20,8 +20,8 @@ type referenceKey struct { // deepCopy returns a copy of v that shares no pointed-to, slice, or map data // with v. Unexported struct fields are copied shallowly, because reflect -// cannot set them without unsafe; map keys, channels, functions, and unsafe -// pointers are shared. +// cannot set them without unsafe; pointers to structs with unexported fields, +// map keys, channels, functions, and unsafe pointers are shared. func deepCopy(v reflect.Value) reflect.Value { if !hasReferences(v.Type()) { return v @@ -51,6 +51,20 @@ func hasReferences(t reflect.Type) bool { } } +// hasUnexportedField reports whether t is a struct with at least one +// unexported field of its own; an embedded unexported struct counts. +func hasUnexportedField(t reflect.Type) bool { + if t.Kind() != reflect.Struct { + return false + } + for i := 0; i < t.NumField(); i++ { + if !t.Field(i).IsExported() { + return true + } + } + return false +} + func (c *copier) copy(v reflect.Value) reflect.Value { switch v.Kind() { case reflect.Pointer: @@ -70,8 +84,11 @@ func (c *copier) copy(v reflect.Value) reflect.Value { } } +// copyPointer shares a pointer to a struct with unexported fields: such types +// usually own internal state (locks, buffers, a strings.Builder's self +// pointer) that a copy of the pointee would break or duplicate. func (c *copier) copyPointer(v reflect.Value) reflect.Value { - if v.IsNil() { + if v.IsNil() || hasUnexportedField(v.Type().Elem()) { return v } diff --git a/async/deep_copy_test.go b/async/deep_copy_test.go index 9d37f5c..d0c01a3 100644 --- a/async/deep_copy_test.go +++ b/async/deep_copy_test.go @@ -148,23 +148,53 @@ func TestDeepCopySharesUncopyableKinds(t *testing.T) { } } -func TestDeepCopyUnexportedFieldIsShallow(t *testing.T) { - type hidden struct { - Visible []int - hidden []int - } - original := hidden{Visible: []int{1}, hidden: []int{2}} +type hiddenFields struct { + Visible []int + hidden []int +} + +func TestDeepCopyCopiesExportedFieldBesideUnexported(t *testing.T) { + original := hiddenFields{Visible: []int{1}, hidden: []int{2}} got := copyOf(original) if &got.Visible[0] == &original.Visible[0] { t.Fatalf("deepCopy() shares the exported field") } +} + +func TestDeepCopyUnexportedFieldIsShallow(t *testing.T) { + original := hiddenFields{Visible: []int{1}, hidden: []int{2}} + + got := copyOf(original) + if &got.hidden[0] != &original.hidden[0] { t.Fatalf("deepCopy() copied the unexported field; documented as shared") } } +func TestDeepCopySharesPointerToStructWithUnexportedField(t *testing.T) { + original := &hiddenFields{Visible: []int{1}} + + got := copyOf(original) + + if got != original { + t.Fatalf("deepCopy() = %p, want the original pointer %p", got, original) + } +} + +func TestDeepCopySharesPointerToStructEmbeddingUnexportedStruct(t *testing.T) { + type inner struct{ Items []int } + type outer struct{ inner } + original := &outer{inner{Items: []int{1}}} + + got := copyOf(original) + + if got != original { + t.Fatalf("deepCopy() = %p, want the original pointer %p", got, original) + } +} + func TestHasReferences(t *testing.T) { tests := []struct { name string diff --git a/docs/adr/0001-async-get-deep-copy.md b/docs/adr/0001-async-get-deep-copy.md new file mode 100644 index 0000000..9416906 --- /dev/null +++ b/docs/adr/0001-async-get-deep-copy.md @@ -0,0 +1,28 @@ +# 0001 — async.Container.Get returns a deep copy + +- Status: accepted (2026-11-21) + +## Context + +The `async` package documents `Container` as safe for concurrent use, and `Container.Get` said it "copies the stored value". It assigned or converted the stored value shallowly, so slices, maps and pointed-to data were shared between the container and every goroutine that called `Get` for the key. Two readers writing what they received raced: silent corruption for slices, `fatal error: concurrent map writes` for maps. The owner chose to make `Get` return a deep copy rather than only documenting the sharing. + +## Decision + +- `Get` deep-copies the stored value with an unexported reflect-based copier before the assign and convert paths of `assignValue`. The slice-to-array length check still runs before `Convert`; the JSON fallback, key validation and error texts are unchanged. Standard library only, no new exported names, no `unsafe`. +- Kinds covered: pointers get a new pointee; slices a new backing array (`len == cap`); maps a new map with deep-copied values; arrays element-wise; structs have their exported fields deep-copied; interfaces have their dynamic value copied with its type preserved. Nil stays nil. +- A memo keyed by type and address (plus len and cap for slices) maps every pointer, map and slice already copied to its copy, so shared references stay shared within the copy and self-referencing values terminate. +- Fast path: a type that reaches no pointer, slice, map or interface through arrays and struct fields is returned unchanged. +- Limits, documented on `Get` and in the README: + - unexported struct fields are copied shallowly, including exported fields promoted from an embedded unexported struct (the embedded field itself is unexported); + - pointers to structs with unexported fields are shared as-is, since such types (`*strings.Builder`, `*bytes.Buffer`, `*sync.WaitGroup`, `*sql.DB`) usually own internal state that a copy would break or duplicate; + - map keys, channels, functions and unsafe pointers are shared; + - values neither assignable nor convertible to the destination go through the JSON round trip, as before. +- `Get` reads the value and its error under the read lock and copies outside it, so writers do not wait for in-flight copies. This is safe because the container never mutates a stored value; it only replaces map entries. + +## Consequences + +- Behavior change at v0: released as MINOR v0.2.0 and called out in the release notes. `Set`/`TrySet` document that a stored value must not be modified afterwards. +- `Get` no longer returns the identity of stored deep-copyable pointers, slices and maps; code that relied on observing later writes through them must change. +- Cost (`BenchmarkContainerGet`, before → after): `int` 94 → 117 ns/op and flat struct 101 → 208 ns/op with no extra allocation; `[]int` of 1000 98 ns → 5.6 µs, 8217 B, 3 allocs; map of 100 96 ns → 10.7 µs, 3576 B, 7 allocs; nested struct 98 ns → 1.6 µs, 488 B, 10 allocs. +- Copy recursion depth is proportional to the value's nesting depth or linked-list length. +- Interior pointers into copied arrays or slices (for example a pointer to an element of a stored slice) are not re-aliased to the copy; they get their own pointee.