Skip to content

docs(bind): require strictly comparable bound value types #246

Description

@linkdata

Problem

bind.New and Binder describe T only as comparable, but the default setter evaluates value != *b.ptr. The generic constraint does not guarantee that this comparison cannot panic: any and comparable structs containing interface fields can hold dynamically uncomparable slices, maps, or functions.

package main

import (
	"sync"

	"github.com/linkdata/jaws/lib/bind"
)

type state struct {
	Value any
}

func main() {
	var mu sync.RWMutex
	value := state{Value: []int{1}}
	b := bind.New(&mu, &value)

	_ = b.JawsSet(nil, state{Value: []int{2}})
}

This panics with:

runtime error: comparing uncomparable type []int

The relevant implementation is the default equality check in lib/bind/binder.go.

Resolution

Narrow the documented supported domain to strictly comparable bound types. In particular:

  • any and other interface types are unsupported as T.
  • Composite types containing interface-typed fields are unsupported.
  • The restriction applies regardless of whether a particular dynamic value would happen to compare successfully.

This is a documentation change, not a request for recovery, reflection-based equality, or another implementation strategy.

Acceptance criteria

  • New documents that T must be strictly comparable and names the panic risk behind the broader comparable constraint.
  • Binder and its default JawsSetLocked behavior describe the same supported domain.
  • The docs explicitly identify any, other interface types, and composites containing interfaces as unsupported.
  • The synopsis remains short and the detailed restriction appears in a following godoc paragraph.
  • go doc ./lib/bind New and go doc ./lib/bind Binder expose the restriction clearly.
  • Runtime behavior and equality semantics remain unchanged.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgoPull requests that update go codeseverity:medium

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions