godebug
packagestandard library
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Report a Vulnerability
Documentation¶
Overview¶
Package godebug makes the settings in the $GODEBUG environment variableavailable to other packages. These settings are often used for compatibilitytweaks, when we need to change a default behavior but want to let usersopt back in to the original. For example GODEBUG=http2server=0 disablesHTTP/2 support in the net/http server.
In typical usage, code should declare a Setting as a globaland then call Value each time the current setting value is needed:
var http2server = godebug.New("http2server")func ServeConn(c net.Conn) {if http2server.Value() == "0" {disallow HTTP/2...}...}Each time a non-default setting causes a change in program behavior,code must callSetting.IncNonDefault to increment a counter that canbe reported byruntime/metrics.Read. The call must only happen whenthe program executes a non-default behavior, not just when the settingis set to a non-default value. This is occasionally (but very rarely)infeasible, in which case the internal/godebugs table entry must setOpaque: true, and the documentation in doc/godebug.md shouldmention that metrics are unavailable.
Conventionally, the global variable representing a godebug is namedfor the godebug itself, with no case changes:
var gotypesalias = godebug.New("gotypesalias") // thisvar goTypesAlias = godebug.New("gotypesalias") // NOT THISThe test in internal/godebugs that checks for use of IncNonDefaultrequires the use of this convention.
Note that counters used with IncNonDefault must be added tovarious tables in other packages. See theSetting.IncNonDefaultdocumentation for details.
Index¶
Constants¶
This section is empty.
Variables¶
This section is empty.
Functions¶
This section is empty.
Types¶
typeSetting¶added ingo1.20
type Setting struct {// contains filtered or unexported fields}A Setting is a single setting in the $GODEBUG environment variable.
funcNew¶added ingo1.20
New returns a new Setting for the $GODEBUG setting with the given name.
GODEBUGs meant for use by end users must be listed in ../godebugs/table.go,which is used for generating and checking various documentation.If the name is not listed in that table, New will succeed but calling Valueon the returned Setting will panic.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] preciselywhen program behavior is changing from the default due to the setting(not just when the setting is different, but when program behavior changes).See theinternal/godebug package comment for more.
func (*Setting)IncNonDefault¶added ingo1.21.0
func (s *Setting) IncNonDefault()
IncNonDefault increments the non-default behavior counterassociated with the given setting.This counter is exposed in the runtime/metrics value/godebug/non-default-behavior/<name>:events.
Note that Value must be called at least once before IncNonDefault.
func (*Setting)Undocumented¶added ingo1.21.0
Undocumented reports whether this is an undocumented setting.
func (*Setting)Value¶added ingo1.20
Value returns the current value for the GODEBUG setting s.
Value maintains an internal cache that is synchronizedwith changes to the $GODEBUG environment variable,making Value efficient to call as frequently as needed.Clients should therefore typically not attempt their owncaching of Value's result.
Source Files