AtomicGo | counter

Documentation | Contributing | Code of Conduct

go get atomicgo.dev/counter

counter

import "atomicgo.dev/counter"

Package counter implements an advanced, fast and thread-safe counter. It optionally collects statistics, like current rate, min / max rate, etc.

Index

• type Counter
  • func NewCounter() *Counter
  • func (c *Counter) CalculateAverageRate(interval time.Duration) float64
  • func (c *Counter) CalculateMaximumRate(interval time.Duration) float64
  • func (c *Counter) CalculateMinimumRate(interval time.Duration) float64
  • func (c *Counter) Count() uint64
  • func (c *Counter) Increment()
  • func (c *Counter) Reset()
  • func (c *Counter) Start() *Counter
  • func (c *Counter) Stop()
  • func (c *Counter) WithAdvancedStats() *Counter

type Counter

Counter is a fast, thread-safe counter. It collects statistics, like current rate, min / max rate, etc. The Counter can go up to `18446744073709551615` (2^64 - 1), as it uses uint64 internally.

Basic usage:

c := counter.NewCounter().Start()
c.Increment()
fmt.Println(c.Count()) // prints 1
c.Stop()
rate := c.CalculateAverageRate(time.Second) // events per second

type Counter struct {
    // contains filtered or unexported fields
}

func NewCounter

func NewCounter() *Counter

NewCounter returns a new Counter.

The counter starts in a stopped state. Call Start() to begin counting.

func (*Counter) CalculateAverageRate

func (c *Counter) CalculateAverageRate(interval time.Duration) float64

CalculateAverageRate calculates the average rate of the counter. It returns the rate in `count / interval`.

For example, to get events per second:

rate := counter.CalculateAverageRate(time.Second)

package main

import (
	"fmt"
	"time"

	"atomicgo.dev/counter"
)

func main() {
	c := counter.NewCounter().Start()

	for i := 0; i < 10; i++ {
		time.Sleep(100 * time.Millisecond)
		c.Increment()
	}

	c.Stop()

	fmt.Println(c.CalculateAverageRate(time.Second))
	// Output should be around 10, as we incremented 10 times in 1 second
}

func (*Counter) CalculateMaximumRate

func (c *Counter) CalculateMaximumRate(interval time.Duration) float64

CalculateMaximumRate calculates the maximum rate of the counter. It returns the rate in `count / interval`. It returns 0 if the counter has not been started yet or has no increments. Needs to be enabled via WithAdvancedStats.

The maximum rate represents the fastest pace at which events occurred.

package main

import (
	"fmt"
	"time"

	"atomicgo.dev/counter"
)

func main() {
	c := counter.NewCounter().WithAdvancedStats().Start()

	for i := 0; i < 10; i++ {
		time.Sleep(100 * time.Millisecond)
		c.Increment()
	}

	c.Stop()

	fmt.Println(c.CalculateMaximumRate(time.Second))
	// Output should be around 10, as we incremented 10 times in 1 second
}

func (*Counter) CalculateMinimumRate

func (c *Counter) CalculateMinimumRate(interval time.Duration) float64

CalculateMinimumRate calculates the minimum rate of the counter. It returns the rate in `count / interval`. It returns 0 if the counter has not been started yet or has no increments. Needs to be enabled via WithAdvancedStats.

The minimum rate represents the slowest pace at which events occurred.

package main

import (
	"fmt"
	"time"

	"atomicgo.dev/counter"
)

func main() {
	c := counter.NewCounter().WithAdvancedStats().Start()

	for i := 0; i < 10; i++ {
		time.Sleep(100 * time.Millisecond)
		c.Increment()
	}

	c.Stop()

	fmt.Println(c.CalculateMinimumRate(time.Second))
	// Output should be around 10, as we incremented 10 times in 1 second
}

func (*Counter) Count

func (c *Counter) Count() uint64

Count returns the current count.

This method is thread-safe and can be called concurrently from multiple goroutines.

func (*Counter) Increment

func (c *Counter) Increment()

Increment increments the counter by 1.

This method is thread-safe and can be called concurrently from multiple goroutines.

package main

import (
	"fmt"

	"atomicgo.dev/counter"
)

func main() {
	c := counter.NewCounter().Start()
	for i := 0; i < 10; i++ {
		c.Increment()
	}

	c.Stop()

	fmt.Println(c.Count())
}

Output

10

func (*Counter) Reset

func (c *Counter) Reset()

Reset stops and resets the counter.

This resets the count to 0 and clears all statistics.

package main

import (
	"fmt"

	"atomicgo.dev/counter"
)

func main() {
	c := counter.NewCounter().Start()
	for i := 0; i < 10; i++ {
		c.Increment()
	}

	c.Reset()

	fmt.Println(c.Count())
}

Output

0

func (*Counter) Start

func (c *Counter) Start() *Counter

Start starts the counter. It returns the counter itself, so you can chain it.

If the counter is already started, this is a no-op.

func (*Counter) Stop

func (c *Counter) Stop()

Stop stops the counter.

This freezes the counter for rate calculations but does not reset the count. If the counter is already stopped, this is a no-op.

func (*Counter) WithAdvancedStats

func (c *Counter) WithAdvancedStats() *Counter

WithAdvancedStats enables the calculation of advanced statistics like CalculateMinimumRate and CalculateMaximumRate. CalculateAverageRate and CalculateCurrentRate are always enabled.

Note: Enabling advanced stats will increase memory usage proportional to the number of increments.

Generated by gomarkdoc

AtomicGo.dev  ·  with ❤️ by @MarvinJWendt | MarvinJWendt.com