Enhance documentation for ITicker interface with detailed description of high resolution time source and utility methods

peter-lawrey · peter-lawrey · commit e6f2812ba24d · 2025-05-23T11:35:11.000+01:00
diff --git a/affinity/src/main/java/net/openhft/ticker/ITicker.java b/affinity/src/main/java/net/openhft/ticker/ITicker.java
@@ -17,8 +17,23 @@
 
 package net.openhft.ticker;
 
-/*
- * Created by Peter Lawrey on 13/07/15.
+/**
+ * Abstraction of a high resolution time source used throughout the library.
+ * <p>
+ * Implementations may be based on {@link System#nanoTime()} or platform
+ * specific timers such as the processor's time stamp counter accessed via
+ * JNI.  The {@linkplain #ticks() tick values} returned are therefore
+ * implementation dependent.  They always increase monotonically but the unit
+ * they represent can vary from nanoseconds to CPU cycles.
+ * <p>
+ * Utility methods are provided to convert these raw ticks into conventional
+ * time units.  For example {@link #toNanos(long)} converts the supplied number
+ * of ticks to nanoseconds and {@link #toMicros(double)} converts them to
+ * microseconds.
+ * <p>
+ * This interface is typically accessed via the {@link net.openhft.ticker.Ticker}
+ * helper class which selects the best available implementation for the
+ * running platform.
  */
 public interface ITicker {
     long nanoTime();
