From 74726defe99bb1e19cee35e27db697085f06fda1 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Fri, 8 Mar 2024 21:01:17 -0500 Subject: internal/godebugs: test for use of IncNonDefault A few recent godebugs are missing IncNonDefault uses. Test for that, so that people remember to do it. Filed bugs for the missing ones. For #66215. For #66216. For #66217. Change-Id: Ia3fd10fd108e1b003bb30a8bc2f83995c768fab6 Reviewed-on: https://go-review.googlesource.com/c/go/+/570275 LUCI-TryBot-Result: Go LUCI Reviewed-by: Damien Neil --- src/internal/godebug/godebug.go | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) (limited to 'src/internal/godebug') diff --git a/src/internal/godebug/godebug.go b/src/internal/godebug/godebug.go index 36bfeaccc4..0756d313e6 100644 --- a/src/internal/godebug/godebug.go +++ b/src/internal/godebug/godebug.go @@ -22,8 +22,23 @@ // } // // Each time a non-default setting causes a change in program behavior, -// code should call [Setting.IncNonDefault] to increment a counter that can -// be reported by [runtime/metrics.Read]. +// code must call [Setting.IncNonDefault] to increment a counter that can +// be reported by [runtime/metrics.Read]. The call must only happen when +// the program executes a non-default behavior, not just when the setting +// is set to a non-default value. This is occasionally (but very rarely) +// infeasible, in which case the internal/godebugs table entry must set +// Opaque: true, and the documentation in doc/godebug.md should +// mention that metrics are unavailable. +// +// Conventionally, the global variable representing a godebug is named +// for the godebug itself, with no case changes: +// +// var gotypesalias = godebug.New("gotypesalias") // this +// var goTypesAlias = godebug.New("gotypesalias") // NOT THIS +// +// The test in internal/godebugs that checks for use of IncNonDefault +// requires the use of this convention. +// // Note that counters used with IncNonDefault must be added to // various tables in other packages. See the [Setting.IncNonDefault] // documentation for details. @@ -70,6 +85,11 @@ type value struct { // To disable that panic for access to an undocumented setting, // prefix the name with a #, as in godebug.New("#gofsystrace"). // The # is a signal to New but not part of the key used in $GODEBUG. +// +// Note that almost all settings should arrange to call [IncNonDefault] precisely +// when program behavior is changing from the default due to the setting +// (not just when the setting is different, but when program behavior changes). +// See the [internal/godebug] package comment for more. func New(name string) *Setting { return &Setting{name: name} } -- cgit v1.3-5-g9baa