> For the complete documentation index, see [llms.txt](https://docs.xplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xplatform.com/performance/benchmark-suite/modules/time-module.md).

# 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:

```bash
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:

```bash
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:

```bash
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

```bash
# 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

```bash
$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

```bash
$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()

```bash
$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

```bash
$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:

```java
// 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:

```java
// 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:

```java
// 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](/performance/benchmark-suite/modules/aep-module.md) to see time usage in end-to-end benchmarks
* Explore [Serialization Module](/performance/benchmark-suite/modules/serialization-module.md) for message encoding benchmarks
* Return to [Modules Overview](/performance/benchmark-suite/modules.md) for other modules