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 well-structured and highly readable. It uses a clear interface with documented methods, each focused on a single responsibility. Nesting is minimal, with the deepest logic confined to short loops inside default methods. Javadoc comments clearly explain intent, especially for non-obvious behavior like the high-resolution time origin and waitObject's condition handling. The code is concise without being terse; imports are grouped logically. Action granularity is appropriate — most lines perform one logical step. Reading flow is natural, with methods ordered from simple getters to more complex utility methods. Minor deductions: the waitForFuture method's line-wrapped signature slightly disrupts flow, and the while(true) loops could be slightly refactored, but overall this is production-quality readable code.
Run 3
The code is well-structured and highly readable. It uses a clear interface with meaningful method names and thorough Javadoc comments explaining intent and edge cases. The class is organized logically, with system time, time retrieval, sleeping, and future-waiting methods grouped cohesively. Nesting is minimal, with only necessary synchronization and loop constructs. Action granularity is appropriate — most lines perform a single operation, and control flow is straightforward. The reading flow is natural, guiding the reader from basic clock methods to more complex utilities. Minor deductions: the `waitForFuture` method’s loop and timeout handling are slightly more complex than other methods, and the fully qualified exception in `waitObject` could be imported for clarity. Overall, this code is highly readable and maintainable.
Run 1
Code Structure: The interface logically groups clock operations, waiting utilities, and timer creation into small, focused methods. Nesting: Most methods are flat; waitObject has moderate nesting through synchronization, a loop, and conditionals, while waitForFuture remains manageable. Clarity of intent: Descriptive names, explicit time units, and useful documentation make purpose clear, although retaining and retrying TimeoutException could benefit from an explanatory comment. Code length: Implementations are concise; lengthy nanoseconds 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: The progression from basic time access to higher-level utilities is natural. Minor distractions include inconsistent conditional braces, the fully qualified timeout exception, and slightly awkward multiline formatting in waitForFuture.
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 Javadocs clearly communicate behavior, including monotonic versus wall-clock time. Code length: Implementations are concise; longer documentation provides relevant context rather than unnecessary verbosity. Action granularity: Statements generally perform one action per line, though the conditional exception expression slightly compresses decision-making. Reading flow: Methods follow a natural progression, with consistent spacing and straightforward control flow. Minor drawbacks include inconsistent conditional braces, awkward multiline parameter formatting, and the extra mental effort required to understand exception retention in waitForFuture.
Run 3
Code Structure: The interface logically groups clock access, waiting, and timer creation into small, focused methods. Nesting: Mostly flat; waitObject adds moderate nesting through synchronization, a loop, and conditionals, while early exits keep it manageable. Clarity of intent: Descriptive names, explicit time-unit suffixes, and useful Javadocs clearly explain behavior, including monotonic versus wall-clock time. The retained timeout exception in waitForFuture could benefit from a brief explanation. Code length: Implementations are concise; extensive documentation is justified by timing semantics, though timer overload descriptions repeat. Action granularity: Statements generally perform one action per line. Reading flow: Consistent method boundaries and documentation support natural reading. Minor distractions include inconsistent conditional braces, the fully qualified timeout exception, and unusual multiline parameter formatting.