src/expvar/expvar.go - go.git - Git at Google

 // Copyright 2009 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.

 // Package expvar provides a standardized interface to public variables, such
 // as operation counters in servers. It exposes these variables via HTTP at
 // /debug/vars in JSON format. As of Go 1.22, the /debug/vars request must
 // use GET.
 //
 // Operations to set or modify these public variables are atomic.
 //
 // In addition to adding the HTTP handler, this package registers the
 // following variables:
 //
 //	cmdline   os.Args
 //	memstats  runtime.Memstats
 //
 // The package is sometimes only imported for the side effect of
 // registering its HTTP handler and the above variables. To use it
 // this way, link this package into your program:
 //
 //	import _ "expvar"
 package expvar

 import (
 	"encoding/json"
 	"internal/godebug"
 	"log"
 	"math"
 	"net/http"
 	"os"
 	"runtime"
 	"slices"
 	"strconv"
 	"sync"
 	"sync/atomic"
 	"unicode/utf8"
 )

 // Var is an abstract type for all exported variables.
 type Var interface {
 	// String returns a valid JSON value for the variable.
 	// Types with String methods that do not return valid JSON
 	// (such as time.Time) must not be used as a Var.
 	String() string
 }

 type jsonVar interface {
 	// appendJSON appends the JSON representation of the receiver to b.
 	appendJSON(b []byte) []byte
 }

 // Int is a 64-bit integer variable that satisfies the [Var] interface.
 type Int struct {
 	i atomic.Int64
 }

 func (v *Int) Value() int64 {
 	return v.i.Load()
 }

 func (v *Int) String() string {
 	return string(v.appendJSON(nil))
 }

 func (v *Int) appendJSON(b []byte) []byte {
 	return strconv.AppendInt(b, v.i.Load(), 10)
 }

 func (v *Int) Add(delta int64) {
 	v.i.Add(delta)
 }

 func (v *Int) Set(value int64) {
 	v.i.Store(value)
 }

 // Float is a 64-bit float variable that satisfies the [Var] interface.
 type Float struct {
 	f atomic.Uint64
 }

 func (v *Float) Value() float64 {
 	return math.Float64frombits(v.f.Load())
 }

 func (v *Float) String() string {
 	return string(v.appendJSON(nil))
 }

 func (v *Float) appendJSON(b []byte) []byte {
 	return strconv.AppendFloat(b, math.Float64frombits(v.f.Load()), 'g', -1, 64)
 }

 // Add adds delta to v.
 func (v *Float) Add(delta float64) {
 	for {
 		cur := v.f.Load()
 		curVal := math.Float64frombits(cur)
 		nxtVal := curVal + delta
 		nxt := math.Float64bits(nxtVal)
 		if v.f.CompareAndSwap(cur, nxt) {
 			return
 		}
 	}
 }

 // Set sets v to value.
 func (v *Float) Set(value float64) {
 	v.f.Store(math.Float64bits(value))
 }

 // Map is a string-to-Var map variable that satisfies the [Var] interface.
 type Map struct {
 	m      sync.Map // map[string]Var
 	keysMu sync.RWMutex
 	keys   []string // sorted
 }

 // KeyValue represents a single entry in a [Map].
 type KeyValue struct {
 	Key   string
 	Value Var
 }

 func (v *Map) String() string {
 	return string(v.appendJSON(nil))
 }

 func (v *Map) appendJSON(b []byte) []byte {
 	return v.appendJSONMayExpand(b, false)
 }

 func (v *Map) appendJSONMayExpand(b []byte, expand bool) []byte {
 	afterCommaDelim := byte(' ')
 	mayAppendNewline := func(b []byte) []byte { return b }
 	if expand {
 		afterCommaDelim = '\n'
 		mayAppendNewline = func(b []byte) []byte { return append(b, '\n') }
 	}

 	b = append(b, '{')
 	b = mayAppendNewline(b)
 	first := true
 	v.Do(func(kv KeyValue) {
 		if !first {
 			b = append(b, ',', afterCommaDelim)
 		}
 		first = false
 		b = appendJSONQuote(b, kv.Key)
 		b = append(b, ':', ' ')
 		switch v := kv.Value.(type) {
 		case nil:
 			b = append(b, "null"...)
 		case jsonVar:
 			b = v.appendJSON(b)
 		default:
 			b = append(b, v.String()...)
 		}
 	})
 	b = mayAppendNewline(b)
 	b = append(b, '}')
 	b = mayAppendNewline(b)
 	return b
 }

 // Init removes all keys from the map.
 func (v *Map) Init() *Map {
 	v.keysMu.Lock()
 	defer v.keysMu.Unlock()
 	v.keys = v.keys[:0]
 	v.m.Clear()
 	return v
 }

 // addKey updates the sorted list of keys in v.keys.
 func (v *Map) addKey(key string) {
 	v.keysMu.Lock()
 	defer v.keysMu.Unlock()
 	// Using insertion sort to place key into the already-sorted v.keys.
 	i, found := slices.BinarySearch(v.keys, key)
 	if found {
 		return
 	}
 	v.keys = slices.Insert(v.keys, i, key)
 }

 func (v *Map) Get(key string) Var {
 	i, _ := v.m.Load(key)
 	av, _ := i.(Var)
 	return av
 }

 func (v *Map) Set(key string, av Var) {
 	// Before we store the value, check to see whether the key is new. Try a Load
 	// before LoadOrStore: LoadOrStore causes the key interface to escape even on
 	// the Load path.
 	if _, ok := v.m.Load(key); !ok {
 		if _, dup := v.m.LoadOrStore(key, av); !dup {
 			v.addKey(key)
 			return
 		}
 	}

 	v.m.Store(key, av)
 }

 // Add adds delta to the *[Int] value stored under the given map key.
 func (v *Map) Add(key string, delta int64) {
 	i, ok := v.m.Load(key)
 	if !ok {
 		var dup bool
 		i, dup = v.m.LoadOrStore(key, new(Int))
 		if !dup {
 			v.addKey(key)
 		}
 	}

 	// Add to Int; ignore otherwise.
 	if iv, ok := i.(*Int); ok {
 		iv.Add(delta)
 	}
 }

 // AddFloat adds delta to the *[Float] value stored under the given map key.
 func (v *Map) AddFloat(key string, delta float64) {
 	i, ok := v.m.Load(key)
 	if !ok {
 		var dup bool
 		i, dup = v.m.LoadOrStore(key, new(Float))
 		if !dup {
 			v.addKey(key)
 		}
 	}

 	// Add to Float; ignore otherwise.
 	if iv, ok := i.(*Float); ok {
 		iv.Add(delta)
 	}
 }

 // Delete deletes the given key from the map.
 func (v *Map) Delete(key string) {
 	v.keysMu.Lock()
 	defer v.keysMu.Unlock()
 	i, found := slices.BinarySearch(v.keys, key)
 	if found {
 		v.keys = slices.Delete(v.keys, i, i+1)
 		v.m.Delete(key)
 	}
 }

 // Do calls f for each entry in the map.
 // The map is locked during the iteration,
 // but existing entries may be concurrently updated.
 func (v *Map) Do(f func(KeyValue)) {
 	v.keysMu.RLock()
 	defer v.keysMu.RUnlock()
 	for _, k := range v.keys {
 		i, _ := v.m.Load(k)
 		val, _ := i.(Var)
 		f(KeyValue{k, val})
 	}
 }

 // String is a string variable, and satisfies the [Var] interface.
 type String struct {
 	s atomic.Value // string
 }

 func (v *String) Value() string {
 	p, _ := v.s.Load().(string)
 	return p
 }

 // String implements the [Var] interface. To get the unquoted string
 // use [String.Value].
 func (v *String) String() string {
 	return string(v.appendJSON(nil))
 }

 func (v *String) appendJSON(b []byte) []byte {
 	return appendJSONQuote(b, v.Value())
 }

 func (v *String) Set(value string) {
 	v.s.Store(value)
 }

 // Func implements [Var] by calling the function
 // and formatting the returned value using JSON.
 type Func func() any

 func (f Func) Value() any {
 	return f()
 }

 func (f Func) String() string {
 	v, _ := json.Marshal(f())
 	return string(v)
 }

 // All published variables.
 var vars Map

 // Publish declares a named exported variable. This should be called from a
 // package's init function when it creates its Vars. If the name is already
 // registered then this will log.Panic.
 func Publish(name string, v Var) {
 	if _, dup := vars.m.LoadOrStore(name, v); dup {
 		log.Panicln("Reuse of exported var name:", name)
 	}
 	vars.keysMu.Lock()
 	defer vars.keysMu.Unlock()
 	vars.keys = append(vars.keys, name)
 	slices.Sort(vars.keys)
 }

 // Get retrieves a named exported variable. It returns nil if the name has
 // not been registered.
 func Get(name string) Var {
 	return vars.Get(name)
 }

 // Convenience functions for creating new exported variables.

 func NewInt(name string) *Int {
 	v := new(Int)
 	Publish(name, v)
 	return v
 }

 func NewFloat(name string) *Float {
 	v := new(Float)
 	Publish(name, v)
 	return v
 }

 func NewMap(name string) *Map {
 	v := new(Map).Init()
 	Publish(name, v)
 	return v
 }

 func NewString(name string) *String {
 	v := new(String)
 	Publish(name, v)
 	return v
 }

 // Do calls f for each exported variable.
 // The global variable map is locked during the iteration,
 // but existing entries may be concurrently updated.
 func Do(f func(KeyValue)) {
 	vars.Do(f)
 }

 func expvarHandler(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 	w.Write(vars.appendJSONMayExpand(nil, true))
 }

 // Handler returns the expvar HTTP Handler.
 //
 // This is only needed to install the handler in a non-standard location.
 func Handler() http.Handler {
 	return http.HandlerFunc(expvarHandler)
 }

 func cmdline() any {
 	return os.Args
 }

 func memstats() any {
 	stats := new(runtime.MemStats)
 	runtime.ReadMemStats(stats)
 	return *stats
 }

 func init() {
 	if godebug.New("httpmuxgo121").Value() == "1" {
 		http.HandleFunc("/debug/vars", expvarHandler)
 	} else {
 		http.HandleFunc("GET /debug/vars", expvarHandler)
 	}
 	Publish("cmdline", Func(cmdline))
 	Publish("memstats", Func(memstats))
 }

 // TODO: Use json.appendString instead.
 func appendJSONQuote(b []byte, s string) []byte {
 	const hex = "0123456789abcdef"
 	b = append(b, '"')
 	for _, r := range s {
 		switch {
 		case r < ' ' || r == '\\' || r == '"' || r == '<' || r == '>' || r == '&' || r == '\u2028' || r == '\u2029':
 			switch r {
 			case '\\', '"':
 				b = append(b, '\\', byte(r))
 			case '\n':
 				b = append(b, '\\', 'n')
 			case '\r':
 				b = append(b, '\\', 'r')
 			case '\t':
 				b = append(b, '\\', 't')
 			default:
 				b = append(b, '\\', 'u', hex[(r>>12)&0xf], hex[(r>>8)&0xf], hex[(r>>4)&0xf], hex[(r>>0)&0xf])
 			}
 		case r < utf8.RuneSelf:
 			b = append(b, byte(r))
 		default:
 			b = utf8.AppendRune(b, r)
 		}
 	}
 	b = append(b, '"')
 	return b
 }
	// Copyright 2009 The Go Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style
	// license that can be found in the LICENSE file.

	// Package expvar provides a standardized interface to public variables, such
	// as operation counters in servers. It exposes these variables via HTTP at
	// /debug/vars in JSON format. As of Go 1.22, the /debug/vars request must
	// use GET.
	//
	// Operations to set or modify these public variables are atomic.
	//
	// In addition to adding the HTTP handler, this package registers the
	// following variables:
	//
	// cmdline os.Args
	// memstats runtime.Memstats
	//
	// The package is sometimes only imported for the side effect of
	// registering its HTTP handler and the above variables. To use it
	// this way, link this package into your program:
	//
	// import _ "expvar"
	package expvar

	import (
	"encoding/json"
	"internal/godebug"
	"log"
	"math"
	"net/http"
	"os"
	"runtime"
	"slices"
	"strconv"
	"sync"
	"sync/atomic"
	"unicode/utf8"
	)

	// Var is an abstract type for all exported variables.
	type Var interface {
	// String returns a valid JSON value for the variable.
	// Types with String methods that do not return valid JSON
	// (such as time.Time) must not be used as a Var.
	String() string
	}

	type jsonVar interface {
	// appendJSON appends the JSON representation of the receiver to b.
	appendJSON(b []byte) []byte
	}

	// Int is a 64-bit integer variable that satisfies the [Var] interface.
	type Int struct {
	i atomic.Int64
	}

	func (v *Int) Value() int64 {
	return v.i.Load()
	}

	func (v *Int) String() string {
	return string(v.appendJSON(nil))
	}

	func (v *Int) appendJSON(b []byte) []byte {
	return strconv.AppendInt(b, v.i.Load(), 10)
	}

	func (v *Int) Add(delta int64) {
	v.i.Add(delta)
	}

	func (v *Int) Set(value int64) {
	v.i.Store(value)
	}

	// Float is a 64-bit float variable that satisfies the [Var] interface.
	type Float struct {
	f atomic.Uint64
	}

	func (v *Float) Value() float64 {
	return math.Float64frombits(v.f.Load())
	}

	func (v *Float) String() string {
	return string(v.appendJSON(nil))
	}

	func (v *Float) appendJSON(b []byte) []byte {
	return strconv.AppendFloat(b, math.Float64frombits(v.f.Load()), 'g', -1, 64)
	}

	// Add adds delta to v.
	func (v *Float) Add(delta float64) {
	for {
	cur := v.f.Load()
	curVal := math.Float64frombits(cur)
	nxtVal := curVal + delta
	nxt := math.Float64bits(nxtVal)
	if v.f.CompareAndSwap(cur, nxt) {
	return
	}
	}
	}

	// Set sets v to value.
	func (v *Float) Set(value float64) {
	v.f.Store(math.Float64bits(value))
	}

	// Map is a string-to-Var map variable that satisfies the [Var] interface.
	type Map struct {
	m sync.Map // map[string]Var
	keysMu sync.RWMutex
	keys []string // sorted
	}

	// KeyValue represents a single entry in a [Map].
	type KeyValue struct {
	Key string
	Value Var
	}

	func (v *Map) String() string {
	return string(v.appendJSON(nil))
	}

	func (v *Map) appendJSON(b []byte) []byte {
	return v.appendJSONMayExpand(b, false)
	}

	func (v *Map) appendJSONMayExpand(b []byte, expand bool) []byte {
	afterCommaDelim := byte(' ')
	mayAppendNewline := func(b []byte) []byte { return b }
	if expand {
	afterCommaDelim = '\n'
	mayAppendNewline = func(b []byte) []byte { return append(b, '\n') }
	}

	b = append(b, '{')
	b = mayAppendNewline(b)
	first := true
	v.Do(func(kv KeyValue) {
	if !first {
	b = append(b, ',', afterCommaDelim)
	}
	first = false
	b = appendJSONQuote(b, kv.Key)
	b = append(b, ':', ' ')
	switch v := kv.Value.(type) {
	case nil:
	b = append(b, "null"...)
	case jsonVar:
	b = v.appendJSON(b)
	default:
	b = append(b, v.String()...)
	}
	})
	b = mayAppendNewline(b)
	b = append(b, '}')
	b = mayAppendNewline(b)
	return b
	}

	// Init removes all keys from the map.
	func (v Map) Init() Map {
	v.keysMu.Lock()
	defer v.keysMu.Unlock()
	v.keys = v.keys[:0]
	v.m.Clear()
	return v
	}

	// addKey updates the sorted list of keys in v.keys.
	func (v *Map) addKey(key string) {
	v.keysMu.Lock()
	defer v.keysMu.Unlock()
	// Using insertion sort to place key into the already-sorted v.keys.
	i, found := slices.BinarySearch(v.keys, key)
	if found {
	return
	}
	v.keys = slices.Insert(v.keys, i, key)
	}

	func (v *Map) Get(key string) Var {
	i, _ := v.m.Load(key)
	av, _ := i.(Var)
	return av
	}

	func (v *Map) Set(key string, av Var) {
	// Before we store the value, check to see whether the key is new. Try a Load
	// before LoadOrStore: LoadOrStore causes the key interface to escape even on
	// the Load path.
	if _, ok := v.m.Load(key); !ok {
	if _, dup := v.m.LoadOrStore(key, av); !dup {
	v.addKey(key)
	return
	}
	}

	v.m.Store(key, av)
	}

	// Add adds delta to the *[Int] value stored under the given map key.
	func (v *Map) Add(key string, delta int64) {
	i, ok := v.m.Load(key)
	if !ok {
	var dup bool
	i, dup = v.m.LoadOrStore(key, new(Int))
	if !dup {
	v.addKey(key)
	}
	}

	// Add to Int; ignore otherwise.
	if iv, ok := i.(*Int); ok {
	iv.Add(delta)
	}
	}

	// AddFloat adds delta to the *[Float] value stored under the given map key.
	func (v *Map) AddFloat(key string, delta float64) {
	i, ok := v.m.Load(key)
	if !ok {
	var dup bool
	i, dup = v.m.LoadOrStore(key, new(Float))
	if !dup {
	v.addKey(key)
	}
	}

	// Add to Float; ignore otherwise.
	if iv, ok := i.(*Float); ok {
	iv.Add(delta)
	}
	}

	// Delete deletes the given key from the map.
	func (v *Map) Delete(key string) {
	v.keysMu.Lock()
	defer v.keysMu.Unlock()
	i, found := slices.BinarySearch(v.keys, key)
	if found {
	v.keys = slices.Delete(v.keys, i, i+1)
	v.m.Delete(key)
	}
	}

	// Do calls f for each entry in the map.
	// The map is locked during the iteration,
	// but existing entries may be concurrently updated.
	func (v *Map) Do(f func(KeyValue)) {
	v.keysMu.RLock()
	defer v.keysMu.RUnlock()
	for _, k := range v.keys {
	i, _ := v.m.Load(k)
	val, _ := i.(Var)
	f(KeyValue{k, val})
	}
	}

	// String is a string variable, and satisfies the [Var] interface.
	type String struct {
	s atomic.Value // string
	}

	func (v *String) Value() string {
	p, _ := v.s.Load().(string)
	return p
	}

	// String implements the [Var] interface. To get the unquoted string
	// use [String.Value].
	func (v *String) String() string {
	return string(v.appendJSON(nil))
	}

	func (v *String) appendJSON(b []byte) []byte {
	return appendJSONQuote(b, v.Value())
	}

	func (v *String) Set(value string) {
	v.s.Store(value)
	}

	// Func implements [Var] by calling the function
	// and formatting the returned value using JSON.
	type Func func() any

	func (f Func) Value() any {
	return f()
	}

	func (f Func) String() string {
	v, _ := json.Marshal(f())
	return string(v)
	}

	// All published variables.
	var vars Map

	// Publish declares a named exported variable. This should be called from a
	// package's init function when it creates its Vars. If the name is already
	// registered then this will log.Panic.
	func Publish(name string, v Var) {
	if _, dup := vars.m.LoadOrStore(name, v); dup {
	log.Panicln("Reuse of exported var name:", name)
	}
	vars.keysMu.Lock()
	defer vars.keysMu.Unlock()
	vars.keys = append(vars.keys, name)
	slices.Sort(vars.keys)
	}

	// Get retrieves a named exported variable. It returns nil if the name has
	// not been registered.
	func Get(name string) Var {
	return vars.Get(name)
	}

	// Convenience functions for creating new exported variables.

	func NewInt(name string) *Int {
	v := new(Int)
	Publish(name, v)
	return v
	}

	func NewFloat(name string) *Float {
	v := new(Float)
	Publish(name, v)
	return v
	}

	func NewMap(name string) *Map {
	v := new(Map).Init()
	Publish(name, v)
	return v
	}

	func NewString(name string) *String {
	v := new(String)
	Publish(name, v)
	return v
	}

	// Do calls f for each exported variable.
	// The global variable map is locked during the iteration,
	// but existing entries may be concurrently updated.
	func Do(f func(KeyValue)) {
	vars.Do(f)
	}

	func expvarHandler(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	w.Write(vars.appendJSONMayExpand(nil, true))
	}

	// Handler returns the expvar HTTP Handler.
	//
	// This is only needed to install the handler in a non-standard location.
	func Handler() http.Handler {
	return http.HandlerFunc(expvarHandler)
	}

	func cmdline() any {
	return os.Args
	}

	func memstats() any {
	stats := new(runtime.MemStats)
	runtime.ReadMemStats(stats)
	return *stats
	}

	func init() {
	if godebug.New("httpmuxgo121").Value() == "1" {
	http.HandleFunc("/debug/vars", expvarHandler)
	} else {
	http.HandleFunc("GET /debug/vars", expvarHandler)
	}
	Publish("cmdline", Func(cmdline))
	Publish("memstats", Func(memstats))
	}

	// TODO: Use json.appendString instead.
	func appendJSONQuote(b []byte, s string) []byte {
	const hex = "0123456789abcdef"
	b = append(b, '"')
	for _, r := range s {
	switch {
	case r < ' ' \|\| r == '\\' \|\| r == '"' \|\| r == '<' \|\| r == '>' \|\| r == '&' \|\| r == '\u2028' \|\| r == '\u2029':
	switch r {
	case '\\', '"':
	b = append(b, '\\', byte(r))
	case '\n':
	b = append(b, '\\', 'n')
	case '\r':
	b = append(b, '\\', 'r')
	case '\t':
	b = append(b, '\\', 't')
	default:
	b = append(b, '\\', 'u', hex[(r>>12)&0xf], hex[(r>>8)&0xf], hex[(r>>4)&0xf], hex[(r>>0)&0xf])
	}
	case r < utf8.RuneSelf:
	b = append(b, byte(r))
	default:
	b = utf8.AppendRune(b, r)
	}
	}
	b = append(b, '"')
	return b
	}