tsc

TSC - High-Performance Unix Time in Go

TSC is a Go library that provides extremely low-latency, high-precision Unix timestamps using the processor's Time Stamp Counter register. It's 6-10x faster than and can significantly improve performance for time-sensitive applications. time.Now().UnixNano()

Table of Contents

• Overview
• Key Features
• Getting Started
• Use Cases
• Performance Comparison
• Clock Drift Analysis
• Best Practices
• Virtual Machine Support
• Limitations
• References
• Related Projects

Overview

TSC leverages the processor's Time Stamp Counter (TSC) register to provide extremely fast timestamp generation. With Invariant TSC support, the library offers reliable frequency measurements across multiple cores/CPUs, delivering timestamps with sub-10ns overhead. Unlike the system clock, TSC provides stable invocation costs and higher precision, while still maintaining calibration with the wall clock to minimize drift.

( abs(system_clock - tsc_clock) for each second min: 0.00us, max: 10.75us, mean: 1.18us within 82,800 seconds)

Key Features

• Blazing fast: 6-10x faster than standard time.Now().UnixNano()
• High precision: Better precision than kernel implementations
• Stable overhead: Consistent cost for each invocation (under 10ns)
• Auto-calibration: Periodically aligns with the system clock
• Cross-platform compatibility: Falls back to standard time functions when TSC isn't supported

Getting Started

Basic Usage

package main

import (
	"fmt"
	"github.com/templexxx/tsc"
)

func main() {
	ts := tsc.UnixNano()   // Getting unix nano timestamp
	fmt.Println(ts, tsc.Supported())  // Print result & whether TSC is supported
}

With Calibration

Here is an example of using TSC with calibration

Use Cases

TSC is ideal for applications where timestamp performance matters:

1. High-performance logging systems (timestamp field generation)
2. Benchmarking and performance measurement
3. Low-latency applications with frequent timestamp needs
4. Cloud-native applications with performance constraints

Performance Comparison

Clock Drift Analysis

TSC provides tools to analyze the stability and drift characteristics in your environment:

• Linux testing: Demonstrates how the library handles frequency variations on different hardware qualities. For modern hardware, drift is about 1μs for long-term running.
• macOS testing: Shows excellent stability with minimal drift within 1μs
• Windows testing: Have not been tested yet. May need High-resolution timer support for calibration
• Calibration effects: Visualizations showing how periodic calibration minimizes long-term drift

Detailed drift analysis charts are available in the tools/longdrift directory.

Best Practices

1. Periodic calibration: Call every 5 minutes to align with system clock (NTP adjustments typically occur every 11 minutes) tsc.Calibrate()
2. Verify stability: Use provided tools to verify TSC stability in your environment
3. Ordered execution: Use when measuring execution time of short code segments tsc.ForbidOutOfOrder()
4. Fallback awareness: Check to know if the hardware TSC is being used or if standard time functions are the fallback tsc.Supported()

Virtual Machine Support

When running in virtualized environments:

• Some cloud providers handle TSC clock source correctly (like AWS EC2)
• Feature detection may be limited by CPUID restrictions in VMs
• TSC will be used as clock source when detected as the system clock source
• Verify with your VM provider before deploying in production

Limitations

1. Platform support: Best results on Linux with Intel Enterprise CPUs
2. Hardware quality: Consumer-grade crystals may show higher drift
3. VM uncertainty: Behavior in virtualized environments depends on provider implementation

References

1. Linux gettimeofday implementation details
2. TSC frequency variations with temperature
3. Further analysis of TSC temperature effects
4. Pitfalls of TSC Usage

Related Projects

• Rust TSC implementation (rtsc)