counters

package module
v0.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 11, 2022 License: BSD-3-Clause Imports: 8 Imported by: 3

README

counters

Go Reference

Package counters provides easy to use atomic counters. The counters are defined in groups and each groups can have subgroups resulting in a tree like structure.

Each counter has an associated handle (used in all the operations), name and description.

Supported operations are increment, decrement, min and max.

Entire groups (complete with their subgroups subtree) can be printed.

Documentation

Overview

Package counters provides easy to use atomic counters. The counters are defined in groups and each groups can have subgroups resulting in a tree like structure.

Each counter has an associated handle (used in all the operations), name and description.

Supported operations are increment, decrement, min and max.

Entire groups (complete with their subgroups subtree) can be printed.

Example 
package main

import (
	"fmt"
	"os"

	"github.com/intuitivelabs/counters"
)

var stats counters.Group

var cntFoo counters.Handle
var cntMax counters.Handle

func init() {
	cntDefs := [...]counters.Def{
		{&cntFoo, 0, nil, nil, "FooCounter",
			"example counter"},
		{&cntMax, counters.CntMaxF, nil, nil, "MaxCounter",
			"maximum value seen so far"},
	}
	stats.Init("example_group", nil, len(cntDefs))
	if !stats.RegisterDefs(cntDefs[:]) {
		panic("failed to register counters")
	}
}

func main() {
	stats.Inc(cntFoo)
	stats.Set(cntMax, 1)
	stats.Set(cntMax, 10)
	stats.Sub(cntMax, 1)
	fmt.Println("cntFoo=", stats.Get(cntFoo))
	fmt.Println("cntMax max=", stats.GetMax(cntMax))
	fmt.Println("cntMax crt=", stats.Get(cntMax))
	stats.Print(os.Stdout, "",
		counters.PrFullName|counters.PrVal|counters.PrDesc|counters.PrRec)

}

Output:

cntFoo= 1
cntMax max= 10
cntMax crt= 9
example_group.FooCounter      :      1              		example counter
example_group.MaxCounter      :      9        M:     10		maximum value seen so far

Index

Examples

Constants

View Source 
const (
	// Counter is storing Min values.
	CntMinF = 1 << iota
	// Counter is storing Max values.
	CntMaxF
	// The counter value should be hidden (not printed).
	CntHideVal
	// The whole counter should be hidden
	CntHideAllF
	// Hide value if 0
	CntHideZeroF
	// The counter is not monotonic, no rate should be computed
	CntNonMonoF
)

Counter flags.

View Source 
const (
	// Full counter name, e.g.: group1.group2.counter.
	PrFullName = 1 << iota
	// Print value (cnt: val).
	PrVal
	// Print counter description  (cnt: [val] [desc]).
	PrDesc
	// Print recursively all subgroups.
	PrRec
	// Print only non zero values
	PrHideZero
)

Print flags used by the Group.Print function.

Variables

This section is empty.

Functions

func CopyGrp added in v0.2.0 

func CopyGrp(dst, src *Group, rec bool) int

CopyGrp will copy all the counters from the src Group to dst. If rec is true it will recursively copy the subgroups too (reusing existing subgroups with the same name in dst or creating new destination subgroups if no corresponding one is found or there is not enough space for all the counters). If rec is false the subgroups will be cleared.

Returns 0 on success, -1 if the master group could not be copied or the number of subgroups for each the copy failed.

func FillRate added in v0.2.0 

func FillRate(dst, a, b *Group, units float64, rec bool) int

FillRate will fill/overwrite the counters in the dst group with the difference of the counters from a & b divided by the provided number of units (dst = (a-b)/units). If rec is true, the subgroups will be filled too with the corresponding rate (non existing or too small subgroups in dst will be created). All the groups must have the same number of counters or the function will fail.

Returns 0 on success, -1 if the master group could not be copied or the number of subgroups for each the operation failed (non-matching counters).

func ResetGrp added in v0.2.0 

func ResetGrp(dst *Group, v Val, rec bool)

ResetGrp will set all the counters to v. If rec is true it will reset also all the subgroups.

Types

type CbkF 

type CbkF func(g *Group, h Handle, v Val, p interface{}) Val

CbkF is the type for the callback function called to transform a counter value, when reading it.

The parameters are the group handle, the counter handle, the value to be transformed and an opaque parameter, set when the callback is registered.

It returns the transformed value, which will be returned by the counter read or get function.

type Def 

type Def struct {
	// Counter handle poiner, filled with the allocated
	// handle value if not nil.
	H *Handle
	// Counter flags, e.g. CntHideVal or CntMaxF.
	Flags int
	// Counter callback function, called on read to transform the
	// value (see type CbkF).
	Cbk CbkF
	// Counter callback function opaque parameter.
	// This parameter will be passed to the callback.
	CbP interface{} // callback param
	// Counter name.
	Name string
	// Counter description (short string describing what the counter will do)
	Desc string
}

Def is the structure for registering a counter.

type Group 

type Group struct {
	// Group name.
	Name string

	ExpVar bool // publish expvar version if true
	// contains filtered or unexported fields
}

Group is the type for the internal counter group representation. 

var RootGrp Group

RootGrp contains all the groups defined without a parent group (nil).

func NewGroup 

func NewGroup(Name string, parent *Group, n int) *Group

NewGroup creates a new counter group, with a specified name and parent.

The maximum counters number will be n (it cannot be increased afterwards). If the parent group is nil, the parent will be set to RootGrp.

If the group already exists in parent, the existing group will be returned.

It returns a pointer to the newly created (and initialised) group.

func (*Group) Add 

func (g *Group) Add(h Handle, v Val) Val

Add adds a value to a counter. The counter is specified by its handle.

It returns the new counter value (after the addition).

func (*Group) AddSubGroup 

func (g *Group) AddSubGroup(sg *Group)

AddSubGroup adds a subgroup to the current group.

func (*Group) CheckDefs added in v0.2.0 

func (g *Group) CheckDefs(defs []Def) bool

CheckDefs check if the counters in the group were defined with the defs definitions.

func (*Group) CntNo 

func (g *Group) CntNo() int

CntNo returns the number of counters registered.

func (*Group) Dec 

func (g *Group) Dec(h Handle) Val

Dec decrements the counter current value by 1. The counter is specified by its handle.

It returns the new value.

func (*Group) EqDef added in v0.2.0 

func (g *Group) EqDef(h Handle, d *Def) bool

EqDef checks if counter handle was defined with the def d.

func (*Group) FillHandles added in v0.2.0 

func (g *Group) FillHandles(defs []Def) int

FillHandles fills the handles in a defs slice, if a counters with the correponding name ( defs[].Name) exits in this group. It returns the number of handles filled. For counters that not exits in the group, the corresponding H value in defs will be set to counters.Invalid.

func (*Group) Get 

func (g *Group) Get(h Handle) Val

Get returns the counter current value. If the counter has a defined callback, the callback will be called to transform the value.

The counter is specified by its handle.

func (*Group) GetCounter 

func (g *Group) GetCounter(name string) (Handle, bool)

GetCounter returns a counter handle, given the counter name. If the counter is not found, it will return false.

func (*Group) GetCounterDot added in v0.2.0 

func (g *Group) GetCounterDot(name string) (*Group, Handle, int)

GetCounterDot returns a counter group and handle, given a dot separated subgroup and counter list. E.g.: "foo.bar.counter1" It returns the counter group, and counter handle on success. If not found it will return nil, invalid handle, position of the first not found part if no group could be found and grp, invalid handle , position of not found part if the subgroups could be found but the counter does not exists. Error check: g, c, pos := counters.RootGrpGetCounterDot(name) 

if g == nil || c == counters.Invalid  {
       ERROR("in %s after %s\n", name, name[:pos])
}

func (*Group) GetDesc 

func (g *Group) GetDesc(h Handle) string

GetDesc returns a counter description.

func (*Group) GetFlags 

func (g *Group) GetFlags(h Handle) int

GetFlags returns the flags with which a counter was registered.

func (*Group) GetFullName 

func (g *Group) GetFullName(h Handle) string

GetFullName returns a counter full name, composed of the group prefix and the counter name.

func (*Group) GetGroup 

func (g *Group) GetGroup(gname string) *Group

GetGroup is obsolete and will be removed in future versions, use GetSubGroup instead.

func (*Group) GetMax 

func (g *Group) GetMax(h Handle) Val

GetMax returns the counter maximum value. If the counter has a defined callback, the callback will be called to transform the value.

The counter is specified by its handle.

func (*Group) GetMin 

func (g *Group) GetMin(h Handle) Val

GetMin returns the counter minimum value. If the counter has a defined callback, the callback will be called to transform the value.

The counter is specified by its handle.

func (*Group) GetName 

func (g *Group) GetName(h Handle) string

GetName returns a counter name, given the counter handle.

func (*Group) GetParent 

func (g *Group) GetParent() *Group

GetParent it will return the group parent or nil.

func (*Group) GetSubGroup added in v0.2.0 

func (g *Group) GetSubGroup(gname string) *Group

GetSubGroup returns a subgroup, based on a subgroup name. If no subgroup with the corresponding name exists it will return nil.

GetSubGroup does not work recursively, it will search only at the current level.

func (*Group) GetSubGroupDot added in v0.2.0 

func (g *Group) GetSubGroupDot(gnames string) (*Group, int)

GetSubGroupDot returns a subgroup, based on a dot separated subgroup names string. If no subgroup with the corresponding name exists it will return nil and the start index in string of the first non-existing subgroup.

E.g.: GetSubGroupDot("foo.bar") will look for the subgroup "foo" and if found it will return the subgroup "bar" in "foo".

func (*Group) GetSubGroups 

func (g *Group) GetSubGroups(groups *[]*Group)

GetSubGroups will fill a passed groups array with all the direct subgroups.

func (*Group) GetSubGroupsNo 

func (g *Group) GetSubGroupsNo() int

GetSubGroupsNo will return the number of direct subgroups.

func (*Group) Inc 

func (g *Group) Inc(h Handle) Val

Inc increments the counter current value by 1. The counter is specified by its handle.

It returns the new value.

func (*Group) Init 

func (g *Group) Init(Name string, parent *Group, n int) *Group

Init initialises a new group. It takes 3 parameters: the name of the group, the parent and the maximum supported number of counters in this group (cannot be increased afterwards).

func (*Group) Max 

func (g *Group) Max(h Handle, v Val) Val

Max sets the counter maximum value if v > current value. The counter is specified by its handle.

It returns the new value.

func (*Group) MaxCntNo added in v0.2.0 

func (g *Group) MaxCntNo() int

MaxCntNo returns the maximum numbers of counters that can be used in the group (can be greater then CntNo).

func (*Group) Min 

func (g *Group) Min(h Handle, v Val) Val

Min sets the counter minimum value if v < current value. The counter is specified by its handle.

It returns the new value.

func (*Group) Print 

func (g *Group) Print(w io.Writer, pre string, flags int)

Print prints all the group counters according to the passed flags (PrVal, PrDesc, PrFullName).

func (*Group) PrintCounter added in v0.2.0 

func (g *Group) PrintCounter(w io.Writer, h Handle,
	ident, prefix string, flags int)

PrintCounter prints one counter according to the passed flags. It will print the contents of ident at the start and the counter name will be prefixed by prefix. If prefix is empty and PrFullName is set, the full counter name will be printed.

func (*Group) PrintSubGroups 

func (g *Group) PrintSubGroups(w io.Writer, flags int)

PrintSubGroups prints all the subgroups according to the passed flags (PrVal, PrDesc, PrFullName, PrRec).

If the PrRec is set in the passed flags it will recursively print all the subgroup tree.

func (*Group) Register 

func (g *Group) Register(Name string, Desc string) (Handle, bool)

Register adds a new standard counter based on name and description.

It returns the new counter handle and true on success, or false on error.

func (*Group) RegisterDef 

func (g *Group) RegisterDef(d *Def) (Handle, bool)

RegisterDef adds a new counter to the group, based on a counter Def. It returns the new counter handle and true on success, or garbage and false on error. If the counter was previously registered and it has the same def, the old counter handle will be returned. If the definitions are different it will return error.

func (*Group) RegisterDefs 

func (g *Group) RegisterDefs(defs []Def) bool

RegisterDefs adds several counters to the group, based on an array of counter Def.

It returns true on success (all counter have been added successfully), or false on error (at least one counter failed to be added).

func (*Group) Reset 

func (g *Group) Reset(h Handle, v Val) Val

Reset sets a counter value. The counter is specified by its handle. The difference from Set() is that it re-initializes the counter min and max values.

It returns the new counter value.

func (*Group) Set 

func (g *Group) Set(h Handle, v Val) Val

Set sets a counter value. The counter is specified by its handle.

It returns the new counter value.

func (*Group) SetMax 

func (g *Group) SetMax(h Handle, v Val)

SetMax force-sets directly the counter internal maximum value. The counter is specified by its handle.

func (*Group) SetMin 

func (g *Group) SetMin(h Handle, v Val)

SetMin force-sets directly the counter internal minimum value. The counter is specified by its handle.

func (*Group) Sub 

func (g *Group) Sub(h Handle, v Val) Val

Sub subtracts a value from a counter. The counter is specified by its handle.

It returns the new counter value (after the subtraction).

type Handle 

type Handle int

Handle is the type for the counter handle. 

const (
	// Invalid marks an invalid handle (e.g. set on error).
	Invalid Handle = Handle(-1)
)

type Val 

type Val uint64

Val is the type for the counter value.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.