Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 18 additions & 7 deletions USAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -257,18 +257,29 @@ func main() {

The example contains only a native integer. Formatting and JSON encoding of Go-backed values can invoke host callbacks: while holding the application mutex, do not reenter it or wait for work that needs it. A callback at the owner goroutine must likewise not wait for that owner to handle another request. For complex host values, have the owner construct independent plain data, then encode that data after leaving the ownership or lock boundary. `to_dict()`/`CloneDict()` are shallow copies; freezing the original shared value changes that original rather than creating an isolated copy. Neither substitutes for ownership of nested mutable values.

From Go, use `text := shared.SnapshotString()` to format a snapshot of the
mapping's entries without racing with mapping updates. Formatting callbacks run
after the mapping lock is released; mutable nested values remain shared.
For on-demand debugging and diagnostics in Go, use
`text := shared.SnapshotString()` to capture and format the mapping's entries
without racing with mapping updates. Formatting callbacks run after the mapping
lock is released; mutable nested values remain shared.
Call `SnapshotString` without already holding that dictionary's mutex, and
outside callbacks from operations that hold it, such as key `Hash`/`Equal` or
value `Freeze`. This Go method does not add a Starlark builtin or change default
printing. See [shared_dict methods and callback rules](lib/goidiomatic/README.md#shared_dict).

Snapshot formatting copies entries into temporary memory. Larger or nested
dictionaries can use more bytes than direct formatting; avoiding intermediate
strings and repeated path allocations can offset some work. The net cost depends
on the values, Go version and machine. Run the included comparisons with:
Cycle detection follows list/dict/set references through tuples, nested
`SharedDict` values and structs with unique field names. Nested `SharedDict`
values are not locked; synchronize them separately. Sets capture their elements
before formatting callbacks run. Custom values and Go-created structs with
duplicate field names keep their own `String` behavior. Go-created cycles
consisting only of tuples are not detected. There is no general depth or output
limit.

Snapshot formatting copies entries and tracks container paths, adding temporary
memory and work. Large sets and nested containers can take longer and use more
bytes than direct formatting. Call it only when diagnostic output is needed;
avoid high-frequency business loops. Normal execution and default printing do
not call it automatically. Costs depend on the values, Go version and machine.
Run the included comparisons with:

```bash
go test ./dataconv -run '^$' -bench '^BenchmarkSharedDictReadPaths$' -benchmem
Expand Down
122 changes: 115 additions & 7 deletions dataconv/share.go
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import (
itn "github.com/1set/starlet/internal"
stdjson "go.starlark.net/lib/json"
"go.starlark.net/starlark"
"go.starlark.net/starlarkstruct"
"go.starlark.net/syntax"
)

Expand Down Expand Up @@ -83,6 +84,10 @@ func (s *SharedDict) String() string {
// SnapshotString formats a shallow snapshot of the mapping in insertion order.
// It releases the mapping lock before invoking formatting callbacks. Mutable
// nested values remain shared and require their own synchronization.
// Nested SharedDict values are not locked by this method. Cycle detection spans
// native lists/dictionaries/sets, SharedDict and structs with unique field names,
// following references via tuples. Other values retain their own String behavior.
// Set elements are captured before formatting callbacks run; the values remain shared.
// Call it without holding this dictionary's mutex, and outside callbacks from
// operations that hold it (for example a key's Hash/Equal or a value's Freeze).
func (s *SharedDict) SnapshotString() string {
Expand All @@ -94,12 +99,20 @@ func (s *SharedDict) SnapshotString() string {
}
s.RUnlock()

f := sharedDictFormatter{root: dict, items: items}
if dict == nil {
return name + "()"
}
if len(items) == 0 {
return name + "({})"
}
var f sharedDictFormatter
f.shared = s
f.name = name
f.root = dict
f.items = items
f.WriteString(name)
f.WriteByte('(')
if dict != nil {
f.write(dict, nil)
}
f.write(dict, nil)
f.WriteByte(')')
return f.String()
}
Expand All @@ -109,8 +122,10 @@ func (s *SharedDict) SnapshotString() string {
// keys or invoking host callbacks under the mapping lock.
type sharedDictFormatter struct {
strings.Builder
root *starlark.Dict
items []starlark.Tuple
shared *SharedDict
name string
root *starlark.Dict
items []starlark.Tuple
}

func (f *sharedDictFormatter) write(value starlark.Value, path []starlark.Value) {
Expand Down Expand Up @@ -143,6 +158,21 @@ func (f *sharedDictFormatter) write(value starlark.Value, path []starlark.Value)
f.WriteByte(',')
}
f.WriteByte(')')
case *SharedDict:
dict, name := f.root, f.name
if value != f.shared {
dict, name = value.dict, value.getTypeName()
}
f.WriteString(name)
f.WriteByte('(')
if dict != nil {
f.write(dict, path)
}
f.WriteByte(')')
case *starlark.Set:
f.writeSet(value, path)
case *starlarkstruct.Struct:
f.writeStruct(value, path)
case *starlark.Dict:
f.WriteByte('{')
if sharedDictPathContains(path, value) {
Expand All @@ -153,11 +183,12 @@ func (f *sharedDictFormatter) write(value starlark.Value, path []starlark.Value)
items = value.Items()
}
valuePath := append(path, value)
keyPath := path[:len(path):len(path)]
for i, item := range items {
if i > 0 {
f.WriteString(", ")
}
f.write(item[0], path)
f.write(item[0], keyPath)
f.WriteString(": ")
f.write(item[1], valuePath)
}
Expand All @@ -168,6 +199,83 @@ func (f *sharedDictFormatter) write(value starlark.Value, path []starlark.Value)
}
}

func (f *sharedDictFormatter) writeSet(value *starlark.Set, path []starlark.Value) {
f.WriteString("set([")
if sharedDictPathContains(path, value) {
f.WriteString("...")
} else {
var smallElements [8]starlark.Value
elements := smallElements[:0]
if size := value.Len(); size > len(smallElements) {
elements = make([]starlark.Value, 0, size)
}
iter := value.Iterate()
var element starlark.Value
for iter.Next(&element) {
elements = append(elements, element)
}
iter.Done()
var smallPath [8]starlark.Value
size := len(path) + 1
nextPath := smallPath[:0]
if size >= len(smallPath) {
nextPath = make([]starlark.Value, size, size+1)
} else {
nextPath = smallPath[:size]
}
copy(nextPath, path)
nextPath[size-1] = value
for i, element := range elements {
if i > 0 {
f.WriteString(", ")
}
f.write(element, nextPath)
}
}
f.WriteString("])")
}

func (f *sharedDictFormatter) writeStruct(value *starlarkstruct.Struct, path []starlark.Value) {
names := value.AttrNames()
for i := 1; i < len(names); i++ {
if names[i] == names[i-1] {
// Attr returns only the first entry of duplicate Go fields.
f.WriteString(value.String())
return
}
}
if sharedDictPathContains(path, value) {
f.WriteString("...")
return
}
path = append(path, value)
constructor := value.Constructor()
if name, ok := constructor.(starlark.String); ok {
f.WriteString(name.GoString())
} else {
if constructor == nil {
f.WriteString(value.String())
return
}
f.write(constructor, path)
}
f.WriteByte('(')
for i, name := range names {
if i > 0 {
f.WriteString(", ")
}
f.WriteString(name)
f.WriteString(" = ")
field, _ := value.Attr(name)
if field == nil {
f.WriteString(value.String())
return
}
f.write(field, path)
}
f.WriteByte(')')
}

func sharedDictPathContains(path []starlark.Value, value starlark.Value) bool {
for _, ancestor := range path {
if ancestor == value {
Expand Down
Loading
Loading