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 highly readable with clear structure and intent. It is a well-documented interface with logical organization of methods, flat nesting levels, and natural reading flow. Each method has a single purpose and concise implementation. The waitForFuture method demonstrates clean handling of timeout logic with minimal nesting. Documentation is thorough without being excessive, explaining both purpose and edge cases. Minor deductions for slight verbosity in some comments and the multi-line method signature in waitForFuture.
Run 2
The code is highly readable. Structure is logical: interface constants, core time methods, then default utility methods (waitObject, timer, waitForFuture) that build on those primitives. Nesting is moderate but acceptable—waitObject uses a synchronized block with an inner loop, and waitForFuture uses a try/catch inside a loop, but neither is deeply confusing. Clarity of intent is strong, aided by Javadoc that explains non-obvious behaviors like negative nanoseconds or the caller's responsibility to notify. Code length is reasonable and avoids redundancy by converting Duration to millis. Action granularity is mostly one action per line, though some lines (e.g., the timeout throw with ternary) are slightly dense. Reading flow is natural, progressing from simple to more complex utilities. Minor deductions: the future wait method uses an exception variable as a control flag, which is slightly obscure, and some Javadoc references a TimeoutException that isn't fully validated by the method signature alone.
Run 3
The code is well-structured and highly readable. It clearly separates concerns with focused methods, flat nesting, and descriptive naming. The interface is logically organized, with related methods grouped together and comprehensive Javadoc explaining intent, especially for non-obvious behavior like `waitObject` and `waitForFuture`. Action granularity is appropriate—most lines perform a single coherent step. The main readability issue is slight verbosity in Javadoc (e.g., the long explanation for `nanoseconds()`), but this aids clarity for an abstract clock API. The `waitForFuture` method is slightly more complex due to loop and exception handling, but remains understandable. Overall, the code demonstrates excellent structure, clear intent, and natural reading flow.
Run 1
Code Structure: The interface logically groups clock operations, timers, and waiting helpers into small, cohesive methods. Nesting: Most methods are flat; waitObject has moderate nesting from synchronization, looping, and condition checks, while waitForFuture remains manageable. Clarity of intent: Descriptive names and thorough documentation clearly distinguish wall-clock and monotonic time. The retry behavior and retained timeout exception in waitForFuture could benefit from a brief explanation. Code length: Implementations are concise, and the longer documentation provides useful context rather than unnecessary verbosity. Action granularity: Each statement performs one clear action, with no compressed multi-statement lines. Reading flow: Methods generally progress naturally from basic clock access to higher-level utilities. Minor distractions include inconsistent parameter formatting, omitted braces on short conditionals, and the fully qualified timeout exception name.
Run 2
Code Structure: The interface is logically organized into clock access, sleeping, condition waiting, and timer/future utilities. Nesting: Most methods are flat; waitObject has moderate nesting through synchronization, a loop, and condition checks. Clarity of intent: Descriptive method names, explicit time units, and useful documentation make the purpose clear, though waitForFuture's timeout retry behavior could use explanation. Code length: Implementations are concise; documentation is extensive but largely justified by timing semantics. Action granularity: Statements generally perform one action per line, with no compressed multi-statement lines. Reading flow: Consistent spacing and small methods support natural reading. Minor distractions include unbraced conditionals, the fully qualified timeout exception, and slightly inconsistent method-signature formatting.
Run 3
Code Structure: The interface logically groups clock access, sleeping, timers, and waiting utilities into focused methods. Nesting: Most methods are flat; waitObject and waitForFuture have moderate, manageable nesting. Clarity of intent: Descriptive names, explicit time-unit suffixes, and useful documentation make the API clear, though retrying future.get after a timeout could benefit from an explanatory comment. Code length: Implementations are concise; extensive documentation is mostly justified by timing semantics. Action granularity: Statements generally perform one action per line, with no compressed multi-statement lines. Reading flow: Consistent organization and short methods support natural reading. Minor distractions include inconsistent braces on conditionals, unusual multiline parameter formatting, and a conditional expression inside a throw statement.