https://github.com/atomicgo/counter
🔢 Counter is a fast, thread-safe counter. It collects statstics, like current rate, min / max rate, etc.
https://github.com/atomicgo/counter
atomicgo go golang golang-library
Last synced: about 2 months ago
JSON representation
🔢 Counter is a fast, thread-safe counter. It collects statstics, like current rate, min / max rate, etc.
- Host: GitHub
- URL: https://github.com/atomicgo/counter
- Owner: atomicgo
- License: mit
- Created: 2022-11-24T20:11:34.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-14T22:57:13.000Z (3 months ago)
- Last Synced: 2025-04-13T09:23:36.598Z (2 months ago)
- Topics: atomicgo, go, golang, golang-library
- Language: Go
- Homepage: https://atomicgo.dev
- Size: 60.5 KB
- Stars: 7
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
AtomicGo | counter
---
Documentation
|
Contributing
|
Code of Conduct
---
go get atomicgo.dev/counter
# counter
```go
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](<#Counter>)
- [func NewCounter\(\) \*Counter](<#NewCounter>)
- [func \(c \*Counter\) CalculateAverageRate\(interval time.Duration\) float64](<#Counter.CalculateAverageRate>)
- [func \(c \*Counter\) CalculateMaximumRate\(interval time.Duration\) float64](<#Counter.CalculateMaximumRate>)
- [func \(c \*Counter\) CalculateMinimumRate\(interval time.Duration\) float64](<#Counter.CalculateMinimumRate>)
- [func \(c \*Counter\) Count\(\) uint64](<#Counter.Count>)
- [func \(c \*Counter\) Increment\(\)](<#Counter.Increment>)
- [func \(c \*Counter\) Reset\(\)](<#Counter.Reset>)
- [func \(c \*Counter\) Start\(\) \*Counter](<#Counter.Start>)
- [func \(c \*Counter\) Stop\(\)](<#Counter.Stop>)
- [func \(c \*Counter\) WithAdvancedStats\(\) \*Counter](<#Counter.WithAdvancedStats>)
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
```
```go
type Counter struct {
// contains filtered or unexported fields
}
```
```go
func NewCounter() *Counter
```
NewCounter returns a new Counter.
The counter starts in a stopped state. Call Start\(\) to begin counting.
### func \(\*Counter\) [CalculateAverageRate]()
```go
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)
```
```go
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]()
```go
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.
```go
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]()
```go
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.
```go
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]()
```go
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]()
```go
func (c *Counter) Increment()
```
Increment increments the counter by 1.
This method is thread\-safe and can be called concurrently from multiple goroutines.
```go
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]()
```go
func (c *Counter) Reset()
```
Reset stops and resets the counter.
This resets the count to 0 and clears all statistics.
```go
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]()
```go
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]()
```go
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]()
```go
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](https://atomicgo.dev) ·
> with ❤️ by [@MarvinJWendt](https://github.com/MarvinJWendt) |
> [MarvinJWendt.com](https://marvinjwendt.com)