go-timecache

an AGILira library
go-timecache is a high-performance time caching library for Go that eliminates the overhead of repeated time.Now() calls by maintaining a cached timestamp that is updated at configurable intervals.

Features

  • Zero-allocation time access: Get current time without heap allocations
  • Configurable precision: Choose your ideal balance between accuracy and performance
  • Thread-safe: Safe for concurrent use from multiple goroutines
  • Simple API: Drop-in replacement for time.Now() with minimal code changes
  • Multiple formats: Access time as time.Time, nanoseconds, or formatted string

Performance

Benchmarks show dramatic improvements over time.Now().

FAQ

Frequently Asked Questions about go-timecache.

Quick Start

Part of our Xantos Core, go-timecache provides zero-allocation access to cached time values, eliminating the performance overhead of repeated time.Now() calls in high-throughput scenarios like logging, metrics collection, and real-time data processing.

Installation

bash 
go get github.com/agilira/go-timecache

Usage

bash 
import "github.com/agilira/go-timecache"

// Using the default global cache
now := timecache.CachedTime()
nanos := timecache.CachedTimeNano()  // Zero allocation!

// Create your own cache with custom settings
tc := timecache.NewWithResolution(1 * time.Millisecond)
defer tc.Stop()  // Important: remember to stop when done

customTime := tc.CachedTime()

Performance

CachedTime is ~121x faster than time.Now() and CachedTimeParallel is ~37x faster than parallel time.Now() with Zero allocations in all ops.

bash 
BenchmarkTimeNow-8                      25118025    42.98 ns/op    0 B/op    0 allocs/op
BenchmarkCachedTime-8                   1000000000   0.3549 ns/op  0 B/op    0 allocs/op
BenchmarkCachedTimeNano-8               1000000000   0.3574 ns/op  0 B/op    0 allocs/op
BenchmarkTimeNowUnixNano-8              27188656    42.68 ns/op    0 B/op    0 allocs/op
BenchmarkCachedTimeParallel-8           1000000000   0.1737 ns/op  0 B/op    0 allocs/op
BenchmarkTimeNowParallel-8              184139052    6.417 ns/op   0 B/op    0 allocs/op

Reproduce Benchmarks

bash 
go test -bench=. -benchmem

Frequently Asked Questions

What is go-timecache?

go-timecache is a high-performance time caching library for Go that eliminates the overhead of repeated time.Now() calls by maintaining a cached timestamp that is updated at configurable intervals.

Why should I use go-timecache instead of time.Now()?

  • Performance: go-timecache is ~121x faster than time.Now()
  • Zero allocations: No heap allocations for time access
  • Consistency: Predictable performance regardless of system load
  • Configurable precision: Choose the right balance between accuracy and CPU usage

Is go-timecache thread-safe?

Yes, all methods are thread-safe and can be called concurrently from multiple goroutines without additional synchronization.

How does it work internally?

go-timecache runs a background goroutine that updates a cached timestamp at regular intervals. All access methods use atomic operations to read the cached value safely.

What's the precision of the cached time?

The precision depends on the resolution you choose. The default 500µs resolution means the cached time is updated every 500 microseconds.

Is the cached time always accurate?

The cached time is accurate within the resolution interval. For example, with 1ms resolution, the cached time may be up to 1ms behind the actual time.

Can I use it with time zones?

The cached time is always in UTC. You can convert it to other time zones using Go's time package:

bash 
utcTime := timecache.CachedTime()
localTime := utcTime.Local()

Compatibility and support

go-timecache is designed for Go 1.23+ environments and follows Long-Term Support guidelines to ensure consistent performance across production deployments.

Developer Tools