Skip to content

docs: add memory-model + hot-loop + correlation + panic-semantics godoc #64

@millerjp

Description

@millerjp

Summary

Several load-bearing contracts are missing from the godoc that a consumer would realistically hit:

  • stdlib sync.Map memory-model guarantees ("synchronizes before") transit the wrapper unchanged — not mentioned in doc.go or any method.
  • Len() is O(n) per call — godoc says so, but doesn't warn against calling in a hot loop (users migrating from plain map assume O(1)).
  • Keys() and Values() index positions are not correlated: keys[i] does not correspond to values[i]. A consumer zipping the two slices gets silently wrong mappings.
  • Range callback panic propagates — not caught by the wrapper.
  • Zero-value V vs missing key — struct V stores the zero struct and ok=true; pointer V stores nil and ok=true; missing stores the typed zero and ok=false. The distinction is subtle and not documented with an example.

Scope

Extend godoc on the affected methods in syncmap.go and the relationship/usage sections of doc.go. Add a short example block to doc.go's Quick Start that demonstrates the zero-vs-missing distinction.

Acceptance criteria

  1. go doc github.com/axonops/syncmap Len mentions "not for hot loops" or equivalent.
  2. go doc ... Values warns that indexes don't correlate with Keys().
  3. go doc ... Range states the panic propagation contract.
  4. doc.go has a Zero-value section contrasting pointer V and struct V.
  5. Memory-model pointer ("synchronizes before, per sync.Map docs") on the package comment.

Source: code-reviewer + docs-writer + security-reviewer.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1Important, not blockingdocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions