Skip to content

Clarify concurrency semantics and polish docs/examples#36

Merged
spiegel-im-spiegel merged 1 commit into
masterfrom
docs-and-polish-concurrency-notes
May 9, 2026
Merged

Clarify concurrency semantics and polish docs/examples#36
spiegel-im-spiegel merged 1 commit into
masterfrom
docs-and-polish-concurrency-notes

Conversation

@spiegel-im-spiegel

Copy link
Copy Markdown
Member

Summary

  • document thread-safety semantics for errs.Error and errs.Errors in code comments
  • add README concurrency notes clarifying container-safety vs element-safety
  • add the same thread-safety guidance to .github/copilot-instructions.md
  • reduce extra capacity in Errors.Unwrap() copied slice
  • fix typo in ExampleErrors output (error count)

Validation

  • task test
  • task govulncheck

Both passed locally.

@spiegel-im-spiegel

Copy link
Copy Markdown
Member Author

As a note related to this change set, here is the thread-safety discussion around errs.Error.

  • errs.Errors is concurrency-safe as a container.

    • Container-level operations such as Add, ErrorOrNil, and Unwrap are protected.
  • However, thread-safety is not guaranteed for each error value stored in errs.Errors.

    • This includes cases where an element is an errs.Error.
  • errs.Error itself is not goroutine-safe because it contains a mutable Context map.

    • The instance may be mutated after creation via SetContext or direct field access.
  • We are not adopting a sync.Map replacement for Context at this time.

    • Considering runtime characteristics, readability, implementation complexity, and compatibility, the benefit is currently limited.
  • Operational assumption:

    • In typical error handling, an error instance is mostly finalized at creation time and then used as a read-mostly value.
    • Given this usage pattern, explicitly documenting thread-safety boundaries is more practical than forcing errs.Error itself to be fully concurrency-safe.
  • What we changed in this PR:

    • Added and aligned this guidance in README, code comments, and copilot-instructions so the intended semantics are clear.

@spiegel-im-spiegel spiegel-im-spiegel merged commit e2ff1ac into master May 9, 2026
5 checks passed
@spiegel-im-spiegel spiegel-im-spiegel deleted the docs-and-polish-concurrency-notes branch May 9, 2026 04:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant