lianetm commented on code in PR #15640:
URL: https://github.com/apache/kafka/pull/15640#discussion_r1585466853
##########
clients/src/main/java/org/apache/kafka/clients/consumer/internals/events/CompletableEvent.java:
##########
@@ -16,9 +16,118 @@
*/
package org.apache.kafka.clients.consumer.internals.events;
+import org.apache.kafka.common.utils.Time;
+import org.apache.kafka.common.utils.Timer;
+
+import java.time.Duration;
+import java.util.concurrent.CancellationException;
import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeoutException;
+
+import static java.util.Objects.requireNonNull;
+/**
+ * {@code CompletableEvent} is an interface that is used by both {@link
CompletableApplicationEvent} and
+ * {@link CompletableBackgroundEvent} for common processing and logic. A
{@code CompletableEvent} is one that
+ * allows the caller to get the {@link #future() future} related to the event
and the event's
+ * {@link #deadlineMs() expiration timestamp}.
+ *
+ * @param <T> Return type for the event when completed
+ */
public interface CompletableEvent<T> {
+ /**
+ * Returns the {@link CompletableFuture future} associated with this
event. Any event will have some related
+ * logic that is executed on its behalf. The event can complete in one of
the following ways:
+ *
+ * <ul>
+ * <li>
+ * Success: when the logic for the event completes successfully,
the data generated by that event
+ * (if applicable) is passed to {@link
CompletableFuture#complete(Object)}. In the case where the generic
+ * bound type is specified as {@link Void}, {@code null} is
provided.</li>
+ * <li>
+ * Error: when the the event logic generates an error, the error
is passed to
+ * {@link CompletableFuture#completeExceptionally(Throwable)}.
+ * </li>
+ * <li>
+ * Timeout: when the time spent executing the event logic exceeds
the {@link #deadlineMs() deadline}, an
+ * instance of {@link TimeoutException} should be created and
passed to
+ * {@link CompletableFuture#completeExceptionally(Throwable)}.
+ * </li>
+ * <li>
+ * Cancelled: when an event remains incomplete when the consumer
closes, the future will be
+ * {@link CompletableFuture#cancel(boolean) cancelled}. Attempts
to {@link Future#get() get the result}
Review Comment:
The reaper actually calls `completeExceptionally` with a
`CancellationException` instead of calling `CompletableFuture#cancel(boolean)`.
Unless I'm missing a subtle semantic diff they should achieve the same, but
still, adding a link to `cancel` here would not be accurate I would say.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscr...@kafka.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
