Time Module

The Time module benchmarks the overhead of X Platform's time acquisition APIs. Time acquisition is a critical operation in high-performance systems, and this benchmark helps quantify the cost of different time sources.

Overview

X Platform provides multiple time sources optimized for different use cases:

• Native Time: Uses native (JNI) calls for high-resolution wall-clock time

• Epoch Time: Uses pure Java implementation for wall-clock time

• System.nanoTime(): JVM's monotonic time source

This benchmark measures the overhead (in nanoseconds) of acquiring time from each source.

Test Program

Class: com.neeve.perf.time.Benchmark

The benchmark:

1. Warms up with 10,000 time acquisitions

2. Measures 100,000,000 time acquisitions

3. Reports average overhead per call in nanoseconds

4. Supports concurrent execution across multiple threads

Time Sources

Native Time

Uses JNI to call native high-resolution clock:

java -Dnv.time.usenative=true -cp "libs/*" com.neeve.perf.time.Benchmark --mode native

Characteristics:

• Highest resolution (typically nanosecond precision)

• Slightly higher overhead due to JNI call

• Wall-clock time (can go backwards on NTP adjustments)

Use When: You need highest resolution time and can afford JNI overhead

Epoch Time

Uses pure Java implementation:

java -Dnv.time.usenative=false -cp "libs/*" com.neeve.perf.time.Benchmark --mode epoch

Characteristics:

• Pure Java (no JNI overhead)

• Lower overhead than native

• Wall-clock time (can go backwards on NTP adjustments)

• Resolution depends on JVM (typically microsecond precision)

Use When: You need wall-clock time with lower overhead

System.nanoTime()

Uses JVM's monotonic time source:

java -cp "libs/*" com.neeve.perf.time.Benchmark --mode nano

Characteristics:

• Lowest overhead

• Monotonic (never goes backwards)

• NOT wall-clock time (arbitrary epoch)

• High resolution

Use When: You need to measure elapsed time or durations

Command-Line Parameters

Parameter	Short	Default	Description
--mode	-m	native	Time source: native, epoch, or nano
--threads	-t	1	Number of concurrent threads
--help	-h	-	Print usage information

Running the Benchmark

Basic Usage

# Extract distribution
tar xvf nvx-perf-time-{version}-dist-linux-x86-64.tar.gz
cd nvx-perf-time-{version}

# Run benchmark with native time
$JAVA_HOME/bin/java -cp "libs/*" com.neeve.perf.time.Benchmark --mode native

Test Native Time

$JAVA_HOME/bin/java -cp "libs/*" com.neeve.perf.time.Benchmark --mode native

Example Output:

USING UtlTime.now() [NATIVE TIME IS ENABLED]
[tid 1] Time overhead is 35 nanos

Test Epoch Time

$JAVA_HOME/bin/java -cp "libs/*" com.neeve.perf.time.Benchmark --mode epoch

Example Output:

USING UtlTime.now() [NATIVE TIME IS DISABLED]
[tid 1] Time overhead is 28 nanos

Test System.nanoTime()

$JAVA_HOME/bin/java -cp "libs/*" com.neeve.perf.time.Benchmark --mode nano

Example Output:

USING System.nanoTime()
[tid 1] Time overhead is 22 nanos

Test with Multiple Threads

$JAVA_HOME/bin/java -cp "libs/*" com.neeve.perf.time.Benchmark --mode native --threads 4

Example Output:

USING UtlTime.now() [NATIVE TIME IS ENABLED]
[tid 10] Time overhead is 37 nanos
[tid 11] Time overhead is 36 nanos
[tid 12] Time overhead is 38 nanos
[tid 13] Time overhead is 35 nanos

Interpreting Results

The benchmark reports the average overhead per time acquisition in nanoseconds.

Typical Results (Linux x86-64)

Time Source	Single Thread	Multiple Threads	Resolution
System.nanoTime()	~20-25ns	~20-25ns	Nanosecond
Epoch Time	~25-30ns	~25-30ns	Microsecond
Native Time	~30-40ns	~30-40ns	Nanosecond

Performance Considerations

1. Absolute Overhead:

   • All time sources have sub-40ns overhead

   • Overhead is negligible for most applications

   • Matters most in tight loops or very low latency paths

2. Contention:

   • Time acquisition overhead typically doesn't increase with thread count

   • Modern CPUs have per-core time sources

3. Use Case Selection:

   • Latency Tracking: Use native or epoch time for wall-clock timestamps

   • Duration Measurement: Use System.nanoTime() for elapsed time

   • Hot Paths: Use epoch time for balance of overhead and resolution

Best Practices

For Latency Measurement

Use wall-clock time (native or epoch) to timestamp events:

// Timestamp incoming message
long receiveTime = UtlTime.now();

// Process message...

// Timestamp outgoing message
long sendTime = UtlTime.now();

// Calculate latency
long latency = sendTime - receiveTime;

For Duration Measurement

Use System.nanoTime() for elapsed time:

// Start timing
long startNanos = System.nanoTime();

// Do work...

// Calculate duration
long durationNanos = System.nanoTime() - startNanos;

For High-Frequency Calls

If time acquisition is in a critical path called millions of times per second, prefer epoch time:

// Configure at startup
System.setProperty("nv.time.usenative", "false");

// In critical path
long timestamp = UtlTime.now(); // Uses epoch time (lower overhead)

System Properties

Property	Values	Description
nv.time.usenative	true/false	Enable/disable native time (default: true)

Next Steps

• Review AEP Module to see time usage in end-to-end benchmarks

• Explore Serialization Module for message encoding benchmarks

• Return to Modules Overview for other modules