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()))) {} else { return; }
long currentTimeMs = milliseconds();
if (!((currentTimeMs >= deadlineMs))) {} else { 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))) {} else {
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 with clear interfaces, helpful Javadoc, and reasonable method decomposition. Intent is generally clear, and most operations are concise. However, readability is reduced by awkward inverted conditionals in `waitObject` and `waitForFuture` (e.g., `if (!((condition.get()))) {} else { return; }`), which disrupt the natural reading flow and add unnecessary nesting. The empty blocks with `else` create visual noise and make the logic harder to follow than a simple negated condition with an early return or throw. The `waitForFuture` method also uses a loop with a captured `TimeoutException` pattern that, while functional, is less straightforward than it could be. These issues lower the score despite the overall strong documentation and organization. Improvements would include rewriting conditions in a direct style and flattening control flow.
Run 2
The code has a clear purpose and good Javadoc comments, but readability suffers due to several factors. The `waitObject` method is convoluted: it uses a `while (true)` loop with awkward empty-if blocks (`if (!((condition.get()))) {} else { return; }`) instead of straightforward boolean expressions, making intent ambiguous. Similarly, `waitForFuture` uses inverted conditionals with empty blocks and a time-out exception variable, which obscures logical flow. Nesting levels are moderate but some methods could be simplified. Action granularity is reasonable, with generally one action per line, but the unusual conditional style creates extra noise. The code length is concise but at the expense of clarity. Reading flow is disrupted by the unnatural `if (!(...)) {} else { ... }` patterns, which should be rewritten as `if (condition) { return; }` and `if (deadlineNs <= nowNs) { throw ...; }` to improve comprehension. Packing and interface design are otherwise clean, with good separation of concerns.
Run 3
The code has good structure and documentation, with clear intent in method signatures and Javadoc. However, readability is significantly harmed by the awkward conditional style in waitObject() and waitForFuture(), using `if (!(condition)) {} else { ... }` instead of idiomatic `if (!condition) { ... }`. This pattern obscures the logic and breaks natural reading flow. The waitObject() method uses a `while (true)` loop with conditions embedded in empty if-blocks, making the control flow harder to follow. Nesting is generally flat, which is positive, and action granularity is mostly one action per line. Variable naming is clear, and method purposes are well-documented. The interface is concise overall, but the unnatural conditional formatting and non-idiomatic boolean checks reduce readability to below average.
Run 1
Code Structure: The interface is logically organized into clock, sleep, timer, and waiting operations, with helpful documentation. Nesting: Most methods are flat, but waiting methods introduce moderate nesting through synchronization, loops, conditionals, and exception handling. Clarity of intent: Descriptive names and Javadocs explain purpose well; however, negated conditions with empty branches obscure straightforward return and timeout checks. Code length: Generally concise, though redundant parentheses and empty branches add unnecessary syntax. Action granularity: Most statements perform one action per line, but inline conditional blocks compress control flow and actions together. Reading flow: Method ordering and spacing are mostly natural, but the inverted if/else patterns interrupt comprehension and require mental simplification.
Run 2
Code Structure: The interface is logically organized into clock access, waiting, and timer methods, with useful documentation. Nesting: Most methods are flat, but waitObject combines synchronization, a loop, and conditional branches; waitForFuture adds a try/catch inside a loop. Clarity of intent: Descriptive method names and explicit time units clarify purpose, but negated conditions with empty branches and redundant parentheses obscure straightforward checks. Code length: Generally concise, although verbose documentation and unnecessarily elaborate conditionals increase reading effort. Action granularity: Most lines express one action, but inline empty branches, returns, and throws compress control flow awkwardly. Reading flow: Method ordering and documentation support natural navigation, while unconventional conditional formatting and the long timeout-throw line interrupt comprehension.
Run 3
Code Structure: The interface logically groups clock operations and related waiting utilities into focused methods. Nesting: Most methods are flat, but synchronized loops, conditionals, and try/catch blocks add moderate nesting. Clarity of intent: Descriptive names and useful documentation explain time units and behavior; however, negated conditions with empty branches obscure straightforward return and timeout checks. Code length: Generally concise, although redundant parentheses and empty branches add unnecessary syntax. Action granularity: Most lines perform one action, but inline if/else statements combine conditions and control-flow actions, reducing scanability. Reading flow: Method organization and documentation provide a natural progression, interrupted by awkward conditional formatting and long exception statements. Replacing empty-branch conditionals with direct positive checks would substantially improve readability.