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 a clean, well-organized interface with clear purpose and consistent style. Structure is logical, with constants, abstract methods, and default methods grouped coherently. Nesting is minimal; the only nested blocks are in waitObject and waitForFuture, both kept flat and readable. Intent is explicit through clear method names and thorough Javadoc comments. Code length is concise for the functionality provided, avoiding unnecessary verbosity. Action granularity is appropriate, with one logical operation per line in most cases. Reading flow follows a natural top-down progression: basic time methods, then waiting/timer utilities. Minor deductions could be made for the slightly awkward line break in the waitForFuture signature and the fully-qualified exception reference, but overall readability is excellent.
Run 3
The code is well-structured and readable. It clearly separates interface methods, uses concise Javadoc comments to explain intent, and follows a logical order: core time methods, utility methods, then future handling. Nesting is moderate—waitObject and waitForFuture use loops but remain understandable. Action granularity is mostly one action per line, though some lines like 'throw new org.apache.kafka.common.errors.TimeoutException(...)' are long but justified. Reading flow is natural. Minor issues: the long fully-qualified exception name adds clutter, and default method implementations could benefit from more whitespace or helper methods. Overall, the code balances clarity and conciseness effectively.
Run 1
Code Structure: The interface logically groups clock access, waiting, and timer creation into small, focused methods. Nesting: Most methods are flat; waitObject adds moderate nesting through synchronization, a loop, and conditionals, but remains easy to follow. Clarity of intent: Descriptive names and thorough documentation clearly distinguish wall-clock and monotonic time. The reason for retrying future.get after a timeout could use a short comment. Code length: Implementations are concise, with documentation contributing useful context rather than unnecessary code. Action granularity: Each statement generally performs one action, with no crowded multi-statement lines. Reading flow: Consistent formatting and straightforward control flow make reading natural. Minor distractions include inconsistent brace usage, the multiline waitForFuture signature, and the 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 synchronization/loop/conditional nesting, while waitForFuture remains manageable. Clarity of intent: Descriptive names, explicit time-unit suffixes, and useful Javadoc clearly communicate behavior. The retained timeout exception and retry loop could benefit from a brief explanation. Code length: Implementations are concise; lengthy documentation is mostly justified by subtle timing semantics. Action granularity: Statements generally perform one action per line, though the conditional throw expression is slightly denser. Reading flow: Method organization and consistent spacing support natural reading, with minor distractions from inconsistent brace usage, multiline parameter formatting, and the fully qualified timeout exception.
Run 3
Code Structure: The interface is logically organized into clock access, sleeping, condition waiting, timer creation, and future waiting. Nesting: Most methods are flat; waitObject adds moderate nesting through synchronization, a loop, and conditionals. Clarity of intent: Descriptive method names, unit-specific variables, and detailed documentation make purposes clear, though the retained timeout exception and retry loop require some interpretation. Code length: Implementations are concise, with documentation adding useful context rather than unnecessary bulk. Action granularity: Statements generally perform one action per line; the conditional exception expression is slightly denser. Reading flow: Consistent formatting and focused methods support natural reading, with minor distractions from brace-free conditionals, the fully qualified timeout exception, and the unusually split waitForFuture signature.