Class Stopwatch

java.lang.Object
cloud.opencode.base.core.Stopwatch
public final class Stopwatch extends Object
Stopwatch - A lightweight timing utility for measuring elapsed time 秒表 - 用于测量经过时间的轻量级计时工具

This class provides a simple and efficient way to measure elapsed time, commonly used for performance testing and debugging.

该类提供了一种简单高效的方式来测量经过的时间，通常用于性能测试和调试。

Features | 主要功能:

  • High-precision timing using System.nanoTime() - 使用 System.nanoTime() 实现高精度计时
  • Start, stop, reset, and resume operations - 支持开始、停止、重置和恢复操作
  • Multiple time unit conversions - 多种时间单位转换
  • Fluent API design - 流式 API 设计

Usage Examples | 使用示例:

// Basic usage | 基本用法
Stopwatch sw = Stopwatch.createStarted();
// ... do something
long elapsedMs = sw.elapsed(TimeUnit.MILLISECONDS);
System.out.println("Elapsed: " + sw);  // "Elapsed: 123.4 ms"

// Manual control | 手动控制
Stopwatch sw = Stopwatch.createUnstarted();
sw.start();
// ... do something
sw.stop();
Duration duration = sw.elapsed();

// Fluent style | 流式风格
Stopwatch.createStarted()
    .stop()
    .reset()
    .start();

Thread Safety | 线程安全:

This class is NOT thread-safe. For concurrent timing, use external synchronization.

此类非线程安全。如需并发计时，请使用外部同步。

Since:
JDK 25, opencode-base-core V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static Stopwatch
    createStarted()
    Creates and starts a stopwatch 创建并启动秒表
    static Stopwatch
    createUnstarted()
    Creates an unstarted stopwatch 创建未启动的秒表
    Duration
    elapsed()
    Returns the elapsed time as a Duration 返回经过的时间（Duration 格式）
    long
    elapsed(TimeUnit unit)
    Returns the elapsed time in the specified time unit 返回指定时间单位的经过时间
    long
    elapsedMillis()
    Returns the elapsed time in milliseconds 返回经过的毫秒数
    long
    elapsedNanos()
    Returns the elapsed time in nanoseconds 返回经过的纳秒数
    long
    elapsedSeconds()
    Returns the elapsed time in seconds 返回经过的秒数
    boolean
    isRunning()
    Returns whether the stopwatch is currently running 返回秒表是否正在运行
    Stopwatch
    reset()
    Resets the stopwatch to zero and stops it 重置秒表为零并停止
    Stopwatch
    start()
    Starts or resumes the stopwatch 启动或恢复秒表
    Stopwatch
    stop()
    Stops the stopwatch 停止秒表
    String
    toString()
    Returns a human-readable string representation of the elapsed time 返回人类可读的经过时间字符串

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Method Details

    • createUnstarted

      public static Stopwatch createUnstarted()
      Creates an unstarted stopwatch 创建未启动的秒表
      Returns:
      a new unstarted stopwatch

    • createStarted

      public static Stopwatch createStarted()
      Creates and starts a stopwatch 创建并启动秒表
      Returns:
      a new started stopwatch

    • start

      public Stopwatch start()
      Starts or resumes the stopwatch 启动或恢复秒表
      Returns:
      this stopwatch for fluent chaining
      Throws:
      IllegalStateException - if the stopwatch is already running

    • stop

      public Stopwatch stop()
      Stops the stopwatch 停止秒表
      Returns:
      this stopwatch for fluent chaining
      Throws:
      IllegalStateException - if the stopwatch is not running

    • reset

      public Stopwatch reset()
      Resets the stopwatch to zero and stops it 重置秒表为零并停止
      Returns:
      this stopwatch for fluent chaining

    • isRunning

      public boolean isRunning()
      Returns whether the stopwatch is currently running 返回秒表是否正在运行
      Returns:
      true if running, false otherwise

    • elapsed

      public Duration elapsed()
      Returns the elapsed time as a Duration 返回经过的时间（Duration 格式）
      Returns:
      the elapsed duration

    • elapsed

      public long elapsed(TimeUnit unit)
      Returns the elapsed time in the specified time unit 返回指定时间单位的经过时间
      Parameters:
      unit - the desired time unit
      Returns:
      the elapsed time in the specified unit

    • elapsedNanos

      public long elapsedNanos()
      Returns the elapsed time in nanoseconds 返回经过的纳秒数
      Returns:
      elapsed nanoseconds

    • elapsedMillis

      public long elapsedMillis()
      Returns the elapsed time in milliseconds 返回经过的毫秒数
      Returns:
      elapsed milliseconds

    • elapsedSeconds

      public long elapsedSeconds()
      Returns the elapsed time in seconds 返回经过的秒数
      Returns:
      elapsed seconds

    • toString

      public String toString()
      Returns a human-readable string representation of the elapsed time 返回人类可读的经过时间字符串

      The time unit is automatically selected based on the magnitude:

      • Less than 1 microsecond: nanoseconds (e.g., "123 ns")
      • Less than 1 millisecond: microseconds (e.g., "123.4 μs")
      • Less than 1 second: milliseconds (e.g., "123.4 ms")
      • Less than 1 minute: seconds (e.g., "12.34 s")
      • Otherwise: minutes (e.g., "1.23 min")
      Overrides:
      toString in class Object
      Returns:
      a formatted string representation