Source code
package org.apache.kafka.common.utils;
import java.time.Duration;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import java.util.function.Supplier;
/**
* An interface abstracting the clock to use in unit testing classes that make use of clock time.
*
* Implementations of this class should be thread-safe.
*/
public interface Time {
Time SYSTEM = SystemTime.getSystemTime();
/**
* Returns the current time in milliseconds.
*/
long milliseconds();
/**
* Returns the value returned by `nanoseconds` converted into milliseconds.
*/
default long hiResClockMs() {
return TimeUnit.NANOSECONDS.toMillis(nanoseconds());
}
/**
* Returns the current value of the running JVM's high-resolution time source, in nanoseconds.
*
* <p>This method can only be used to measure elapsed time and is
* not related to any other notion of system or wall-clock time.
* The value returned represents nanoseconds since some fixed but
* arbitrary <i>origin</i> time (perhaps in the future, so values
* may be negative). The same origin is used by all invocations of
* this method in an instance of a Java virtual machine; other
* virtual machine instances are likely to use a different origin.
*/
long nanoseconds();
/**
* Sleep for the given number of milliseconds
*/
void sleep(long ms);
/**
* Wait for a condition using the monitor of a given object. This avoids the implicit
* dependence on system time when calling {@link Object#wait()}.
*
* @param obj The object that will be waited with {@link Object#wait()}. Note that it is the responsibility
* of the caller to call notify on this object when the condition is satisfied.
* @param condition The condition we are awaiting
* @param deadlineMs The deadline timestamp at which to raise a timeout error
*
* @throws org.apache.kafka.common.errors.TimeoutException if the timeout expires before the condition is satisfied
*/
default void waitObject(Object obj, Supplier<Boolean> condition, long deadlineMs) throws InterruptedException {
synchronized (obj) {
while (true) {
if (condition.get())
return;
long currentTimeMs = milliseconds();
if (currentTimeMs >= deadlineMs)
throw new org.apache.kafka.common.errors.TimeoutException("Condition not satisfied before deadline");
obj.wait(deadlineMs - currentTimeMs);
}
}
}
/**
* Get a timer which is bound to this time instance and expires after the given timeout
*/
default Timer timer(long timeoutMs) {
return new Timer(this, timeoutMs);
}
/**
* Get a timer which is bound to this time instance and expires after the given timeout
*/
default Timer timer(Duration timeout) {
return timer(timeout.toMillis());
}
/**
* Wait for a future to complete, or time out.
*
* @param future The future to wait for.
* @param deadlineNs The time in the future, in monotonic nanoseconds, to time out.
* @return The result of the future.
* @param <T> The type of the future.
*/
default <T> T waitForFuture(
Future<T> future,
long deadlineNs
) throws TimeoutException, InterruptedException, ExecutionException {
TimeoutException timeoutException = null;
while (true) {
long nowNs = nanoseconds();
if (deadlineNs <= nowNs) {
throw (timeoutException == null) ? new TimeoutException() : timeoutException;
}
long deltaNs = deadlineNs - nowNs;
try {
return future.get(deltaNs, TimeUnit.NANOSECONDS);
} catch (TimeoutException t) {
timeoutException = t;
}
}
}
}
Run 1
The code is well-structured and clearly organized. Each method has a single responsibility and is documented with Javadoc, which makes the intent explicit. The nesting level is moderate—only two levels deep for the wait loops—which is acceptable and easily readable. Action granularity is strong: most lines contain a single logical operation. The waitObject and waitForFuture methods use clear control flow, with early returns and straightforward condition checks. The only minor readability concerns are the slightly long Javadoc for nanoseconds() and some line wrapping in waitForFuture, which slightly interrupt the natural reading flow. Overall, the code is concise, maintainable, and easy to follow.
Run 2
The code is well-structured with clear separation of concerns and good documentation. The interface methods are logically organized and Javadoc comments explain intent clearly. Nesting is minimal: the deepest nesting is two levels in waitObject and waitForFuture, which is acceptable. Action granularity is generally good, with one operation per line in most cases. The waitForFuture method has slightly more complex logic with a try-catch inside a while loop that could be clearer, but it remains readable. The method signature formatting is a bit unusual with the multi-line parameter list and throws clause, but this appears to be a style convention rather than a problem. Overall, the code is concise, well-documented, and easy to follow.
Run 3
The code is highly readable due to its clean interface design, clear method names, and comprehensive Javadoc. Structure is logical, with methods grouped by functionality and minimal nesting (only two levels in waitObject and waitForFuture). Intent is well-documented; each method's purpose and parameters are clear. The code is concise - no unnecessary lines - and action granularity is appropriate, with one logical operation per line. Reading flow follows a natural progression: basic time methods, sleep, wait utilities, timers, then future handling. Minor deductions: waitForFuture's multi-line method signature is slightly awkward, and the timeout exception reassignment pattern could be more elegant. Overall excellent clarity for a utility interface.
Run 1
Code Structure: The interface logically groups clock operations, waiting utilities, and timer factories into focused methods. Nesting: Most methods are flat; waitObject has moderate synchronized/loop/conditional nesting, while waitForFuture remains manageable. Clarity of intent: Descriptive names, explicit time-unit suffixes, and useful documentation clearly explain wall-clock versus monotonic time. Retaining the last timeout exception is slightly less obvious without a comment. Code length: Implementations are concise, and longer documentation provides relevant context rather than unnecessary repetition. Action granularity: Statements generally perform one action per line, with no compressed multi-statement lines. Reading flow: Consistent method boundaries and straightforward control flow make reading natural. Minor distractions include inconsistent braces around conditionals, unusual multiline parameter formatting, and a fully qualified timeout exception needed to distinguish two exception types.
Run 2
Code Structure: The interface logically groups clock access, waiting, and timer creation into focused methods. Nesting: Most methods are flat; waitObject has moderate nesting through synchronization, a loop, and conditionals, but early exits keep it manageable. Clarity of intent: Descriptive names, explicit time-unit suffixes, and useful documentation make behavior clear. The retained timeout exception in waitForFuture could benefit from a brief explanatory comment. Code length: Implementations are concise; extensive documentation is mostly justified by timing semantics. Action granularity: Statements generally perform one action per line, although the conditional throw expression adds slight complexity. Reading flow: Consistent method organization and whitespace support natural reading. Minor distractions include inconsistent conditional braces, the split waitForFuture signature, and the fully qualified timeout exception needed to distinguish exception types.
Run 3
Code Structure: The interface logically groups clock access, sleeping, timers, and waiting utilities into focused methods. Nesting: Most methods are flat; waitObject introduces moderate nesting through synchronization, a loop, and conditionals, while early returns limit complexity. Clarity of intent: Descriptive method names, explicit time units, and detailed documentation clearly distinguish wall-clock and monotonic time. The timeout retry behavior in waitForFuture could benefit from a brief explanatory comment. Code length: Implementations are concise; documentation is extensive but useful, with minor repetition in timer overloads. Action granularity: Statements generally perform one action per line, although the conditional exception expression is slightly dense. Reading flow: Organization and formatting are mostly natural and consistent. Missing braces around some conditionals, the fully qualified timeout exception, and the unusually split waitForFuture signature create minor reading friction.