Source file src/pkg/expvar/expvar.go

     1	// Copyright 2009 The Go Authors. All rights reserved.
     2	// Use of this source code is governed by a BSD-style
     3	// license that can be found in the LICENSE file.
     4	
     5	// Package expvar provides a standardized interface to public variables, such
     6	// as operation counters in servers. It exposes these variables via HTTP at
     7	// /debug/vars in JSON format.
     8	//
     9	// Operations to set or modify these public variables are atomic.
    10	//
    11	// In addition to adding the HTTP handler, this package registers the
    12	// following variables:
    13	//
    14	//	cmdline   os.Args
    15	//	memstats  runtime.Memstats
    16	//
    17	// The package is sometimes only imported for the side effect of
    18	// registering its HTTP handler and the above variables.  To use it
    19	// this way, link this package into your program:
    20	//	import _ "expvar"
    21	//
    22	package expvar
    23	
    24	import (
    25		"bytes"
    26		"encoding/json"
    27		"fmt"
    28		"log"
    29		"net/http"
    30		"os"
    31		"runtime"
    32		"strconv"
    33		"sync"
    34	)
    35	
    36	// Var is an abstract type for all exported variables.
    37	type Var interface {
    38		String() string
    39	}
    40	
    41	// Int is a 64-bit integer variable that satisfies the Var interface.
    42	type Int struct {
    43		i  int64
    44		mu sync.RWMutex
    45	}
    46	
    47	func (v *Int) String() string {
    48		v.mu.RLock()
    49		defer v.mu.RUnlock()
    50		return strconv.FormatInt(v.i, 10)
    51	}
    52	
    53	func (v *Int) Add(delta int64) {
    54		v.mu.Lock()
    55		defer v.mu.Unlock()
    56		v.i += delta
    57	}
    58	
    59	func (v *Int) Set(value int64) {
    60		v.mu.Lock()
    61		defer v.mu.Unlock()
    62		v.i = value
    63	}
    64	
    65	// Float is a 64-bit float variable that satisfies the Var interface.
    66	type Float struct {
    67		f  float64
    68		mu sync.RWMutex
    69	}
    70	
    71	func (v *Float) String() string {
    72		v.mu.RLock()
    73		defer v.mu.RUnlock()
    74		return strconv.FormatFloat(v.f, 'g', -1, 64)
    75	}
    76	
    77	// Add adds delta to v.
    78	func (v *Float) Add(delta float64) {
    79		v.mu.Lock()
    80		defer v.mu.Unlock()
    81		v.f += delta
    82	}
    83	
    84	// Set sets v to value.
    85	func (v *Float) Set(value float64) {
    86		v.mu.Lock()
    87		defer v.mu.Unlock()
    88		v.f = value
    89	}
    90	
    91	// Map is a string-to-Var map variable that satisfies the Var interface.
    92	type Map struct {
    93		m  map[string]Var
    94		mu sync.RWMutex
    95	}
    96	
    97	// KeyValue represents a single entry in a Map.
    98	type KeyValue struct {
    99		Key   string
   100		Value Var
   101	}
   102	
   103	func (v *Map) String() string {
   104		v.mu.RLock()
   105		defer v.mu.RUnlock()
   106		var b bytes.Buffer
   107		fmt.Fprintf(&b, "{")
   108		first := true
   109		for key, val := range v.m {
   110			if !first {
   111				fmt.Fprintf(&b, ", ")
   112			}
   113			fmt.Fprintf(&b, "\"%s\": %v", key, val)
   114			first = false
   115		}
   116		fmt.Fprintf(&b, "}")
   117		return b.String()
   118	}
   119	
   120	func (v *Map) Init() *Map {
   121		v.m = make(map[string]Var)
   122		return v
   123	}
   124	
   125	func (v *Map) Get(key string) Var {
   126		v.mu.RLock()
   127		defer v.mu.RUnlock()
   128		return v.m[key]
   129	}
   130	
   131	func (v *Map) Set(key string, av Var) {
   132		v.mu.Lock()
   133		defer v.mu.Unlock()
   134		v.m[key] = av
   135	}
   136	
   137	func (v *Map) Add(key string, delta int64) {
   138		v.mu.RLock()
   139		av, ok := v.m[key]
   140		v.mu.RUnlock()
   141		if !ok {
   142			// check again under the write lock
   143			v.mu.Lock()
   144			if _, ok = v.m[key]; !ok {
   145				av = new(Int)
   146				v.m[key] = av
   147			}
   148			v.mu.Unlock()
   149		}
   150	
   151		// Add to Int; ignore otherwise.
   152		if iv, ok := av.(*Int); ok {
   153			iv.Add(delta)
   154		}
   155	}
   156	
   157	// AddFloat adds delta to the *Float value stored under the given map key.
   158	func (v *Map) AddFloat(key string, delta float64) {
   159		v.mu.RLock()
   160		av, ok := v.m[key]
   161		v.mu.RUnlock()
   162		if !ok {
   163			// check again under the write lock
   164			v.mu.Lock()
   165			if _, ok = v.m[key]; !ok {
   166				av = new(Float)
   167				v.m[key] = av
   168			}
   169			v.mu.Unlock()
   170		}
   171	
   172		// Add to Float; ignore otherwise.
   173		if iv, ok := av.(*Float); ok {
   174			iv.Add(delta)
   175		}
   176	}
   177	
   178	// Do calls f for each entry in the map.
   179	// The map is locked during the iteration,
   180	// but existing entries may be concurrently updated.
   181	func (v *Map) Do(f func(KeyValue)) {
   182		v.mu.RLock()
   183		defer v.mu.RUnlock()
   184		for k, v := range v.m {
   185			f(KeyValue{k, v})
   186		}
   187	}
   188	
   189	// String is a string variable, and satisfies the Var interface.
   190	type String struct {
   191		s  string
   192		mu sync.RWMutex
   193	}
   194	
   195	func (v *String) String() string {
   196		v.mu.RLock()
   197		defer v.mu.RUnlock()
   198		return strconv.Quote(v.s)
   199	}
   200	
   201	func (v *String) Set(value string) {
   202		v.mu.Lock()
   203		defer v.mu.Unlock()
   204		v.s = value
   205	}
   206	
   207	// Func implements Var by calling the function
   208	// and formatting the returned value using JSON.
   209	type Func func() interface{}
   210	
   211	func (f Func) String() string {
   212		v, _ := json.Marshal(f())
   213		return string(v)
   214	}
   215	
   216	// All published variables.
   217	var (
   218		mutex sync.RWMutex
   219		vars  map[string]Var = make(map[string]Var)
   220	)
   221	
   222	// Publish declares a named exported variable. This should be called from a
   223	// package's init function when it creates its Vars. If the name is already
   224	// registered then this will log.Panic.
   225	func Publish(name string, v Var) {
   226		mutex.Lock()
   227		defer mutex.Unlock()
   228		if _, existing := vars[name]; existing {
   229			log.Panicln("Reuse of exported var name:", name)
   230		}
   231		vars[name] = v
   232	}
   233	
   234	// Get retrieves a named exported variable.
   235	func Get(name string) Var {
   236		mutex.RLock()
   237		defer mutex.RUnlock()
   238		return vars[name]
   239	}
   240	
   241	// Convenience functions for creating new exported variables.
   242	
   243	func NewInt(name string) *Int {
   244		v := new(Int)
   245		Publish(name, v)
   246		return v
   247	}
   248	
   249	func NewFloat(name string) *Float {
   250		v := new(Float)
   251		Publish(name, v)
   252		return v
   253	}
   254	
   255	func NewMap(name string) *Map {
   256		v := new(Map).Init()
   257		Publish(name, v)
   258		return v
   259	}
   260	
   261	func NewString(name string) *String {
   262		v := new(String)
   263		Publish(name, v)
   264		return v
   265	}
   266	
   267	// Do calls f for each exported variable.
   268	// The global variable map is locked during the iteration,
   269	// but existing entries may be concurrently updated.
   270	func Do(f func(KeyValue)) {
   271		mutex.RLock()
   272		defer mutex.RUnlock()
   273		for k, v := range vars {
   274			f(KeyValue{k, v})
   275		}
   276	}
   277	
   278	func expvarHandler(w http.ResponseWriter, r *http.Request) {
   279		w.Header().Set("Content-Type", "application/json; charset=utf-8")
   280		fmt.Fprintf(w, "{\n")
   281		first := true
   282		Do(func(kv KeyValue) {
   283			if !first {
   284				fmt.Fprintf(w, ",\n")
   285			}
   286			first = false
   287			fmt.Fprintf(w, "%q: %s", kv.Key, kv.Value)
   288		})
   289		fmt.Fprintf(w, "\n}\n")
   290	}
   291	
   292	func cmdline() interface{} {
   293		return os.Args
   294	}
   295	
   296	func memstats() interface{} {
   297		stats := new(runtime.MemStats)
   298		runtime.ReadMemStats(stats)
   299		return *stats
   300	}
   301	
   302	func init() {
   303		http.HandleFunc("/debug/vars", expvarHandler)
   304		Publish("cmdline", Func(cmdline))
   305		Publish("memstats", Func(memstats))
   306	}