package godebug

Import Path
	internal/godebug (on go.dev)

Dependency Relation
	imports 5 packages, and imported by 7 packages

Involved Source Files

	  d godebug.go
		Package godebug makes the settings in the $GODEBUG environment variable
		available to other packages. These settings are often used for compatibility
		tweaks, when we need to change a default behavior but want to let users
		opt back in to the original. For example GODEBUG=http2server=0 disables
		HTTP/2 support in the net/http server.
		
		In typical usage, code should declare a Setting as a global
		and 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 should call [Setting.IncNonDefault] to increment a counter that can
		be reported by [runtime/metrics.Read].
		Note that counters used with IncNonDefault must be added to
		various tables in other packages. See the [Setting.IncNonDefault]
		documentation for details.
Package-Level Type Names (total 4, in which 1 is exported)

	/* sort exporteds by: alphabet | popularity */
	 type Setting (struct)
		A Setting is a single setting in the $GODEBUG environment variable.

		Fields (total 7, none are exported)
			/* 7 unexporteds ... *//* 7 unexporteds: */
			name string
			once sync.Once
			setting *setting
			setting.info *godebugs.Info
			setting.nonDefault atomic.Uint64
			setting.nonDefaultOnce sync.Once
			setting.value atomic.Pointer[value]
		Methods (total 6, in which 5 are exported)
			(*Setting) IncNonDefault()
				IncNonDefault increments the non-default behavior counter
				associated 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.

			(*Setting) Name() string
				Name returns the name of the setting.

			(*Setting) String() string
				String returns a printable form for the setting: name=value.

			(*Setting) Undocumented() bool
				Undocumented reports whether this is an undocumented setting.

			(*Setting) Value() string
				Value returns the current value for the GODEBUG setting s.
				
				Value maintains an internal cache that is synchronized
				with changes to the $GODEBUG environment variable,
				making Value efficient to call as frequently as needed.
				Clients should therefore typically not attempt their own
				caching of Value's result.

			/* one unexported ... *//* one unexported: */
			(*Setting) register()
		Implements (at least 3, in which 1 is exported)
			*Setting : fmt.Stringer
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			*Setting : context.stringer
			*Setting : runtime.stringer
		As Outputs Of (at least one exported)
			func New(name string) *Setting
		As Types Of (total 12, none are exported)
			/* 12 unexporteds ... *//* 12 unexporteds: */
			  var internal/intern.intern *Setting
			  var crypto/tls.tlsmaxrsasize *Setting
			  var crypto/x509.x509sha1 *Setting
			  var crypto/x509.x509usefallbackroots *Setting
			  var math/rand.randautoseed *Setting
			  var mime/multipart.multipartFiles *Setting
			  var mime/multipart.multipartMaxHeaders *Setting
			  var mime/multipart.multipartMaxParts *Setting
			  var net.multipathtcp *Setting
			  var net.netdns *Setting
			  var net/http.http2client *Setting
			  var net/http.http2server *Setting

	/* 3 unexporteds ... *//* 3 unexporteds: */
	 type runtimeStderr (struct)

		Methods (only one, which is exported)
			(*runtimeStderr) Write(b []byte) (int, error)
		Implements (at least 3, in which 2 are exported)
			*runtimeStderr : internal/bisect.Writer
			*runtimeStderr : io.Writer
			/* at least one unexported ... *//* at least one unexported: */
			*runtimeStderr : crypto/tls.transcriptHash
		As Types Of (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			  var stderr

	 type setting (struct)

		Fields (total 4, none are exported)
			/* 4 unexporteds ... *//* 4 unexporteds: */
			info *godebugs.Info
			nonDefault atomic.Uint64
			nonDefaultOnce sync.Once
			value atomic.Pointer[value]
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func lookup(name string) *setting

	 type value (struct)

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			bisect *bisect.Matcher
			text string
		As Types Of (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			  var empty


Package-Level Functions (total 10, in which 1 is exported)

	 func New(name string) *Setting
		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 Value
		on 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.

	/* 9 unexporteds ... *//* 9 unexporteds: */
	 func init()
	 func lookup(name string) *setting
		lookup returns the unique *setting value for the given name.

	 func newIncNonDefault(name string) func()
	 func parse(did map[string]bool, s string)
		parse parses the GODEBUG setting string s,
		which has the form k=v,k2=v2,k3=v3.
		Later settings override earlier ones.
		Parse only updates settings k=v for which did[k] = false.
		It also sets did[k] = true for settings that it updates.
		Each value v can also have the form v#pattern,
		in which case the GODEBUG is only enabled for call stacks
		matching pattern, for use with golang.org/x/tools/cmd/bisect.

	 func registerMetric(name string, read func() uint64)
		registerMetric is provided by package runtime.
		It forwards registrations to runtime/metrics.

	 func setNewIncNonDefault(newIncNonDefault func(string) func())
		setNewIncNonDefault is provided by package runtime.
		The runtime can do
		
			inc := newNonDefaultInc(name)
		
		instead of
		
			inc := godebug.New(name).IncNonDefault
		
		since it cannot import godebug.

	 func setUpdate(update func(string, string))
		setUpdate is provided by package runtime.
		It calls update(def, env), where def is the default GODEBUG setting
		and env is the current value of the $GODEBUG environment variable.
		After that first call, the runtime calls update(def, env)
		again each time the environment variable changes
		(due to use of os.Setenv, for example).

	 func update(def, env string)
		update records an updated GODEBUG setting.
		def is the default GODEBUG setting for the running binary,
		and env is the current value of the $GODEBUG environment variable.

	 func write(fd uintptr, p unsafe.Pointer, n int32) int32
		Since we cannot import os or syscall, use the runtime's write function
		to print to standard error.


Package-Level Variables (total 4, none are exported)

	/* 4 unexporteds ... *//* 4 unexporteds: */
	  var cache sync.Map // name string -> value *atomic.Pointer[string]
		cache is a cache of all the GODEBUG settings,
		a locked map[string]*atomic.Pointer[string].
		
		All Settings with the same name share a single
		*atomic.Pointer[string], so that when GODEBUG
		changes only that single atomic string pointer
		needs to be updated.
		
		A name appears in the values map either if it is the
		name of a Setting for which Value has been called
		at least once, or if the name has ever appeared in
		a name=value pair in the $GODEBUG environment variable.
		Once entered into the map, the name is never removed.

	  var empty value
	  var stderr runtimeStderr
	  var updateMu sync.Mutex

The pages are generated with Golds v0.6.7. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.