This is an automated email from the ASF dual-hosted git repository. sewen pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/flink.git
commit 79ded59e8d0334b44d92f7e313206645685d08da Author: Stephan Ewen <[email protected]> AuthorDate: Wed Nov 4 22:07:20 2020 +0100 [hotfix] Improve JavaDocs of SourceReader. --- .../flink/api/connector/source/SourceReader.java | 23 +++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/flink-core/src/main/java/org/apache/flink/api/connector/source/SourceReader.java b/flink-core/src/main/java/org/apache/flink/api/connector/source/SourceReader.java index aac9ed7..0d37689 100644 --- a/flink-core/src/main/java/org/apache/flink/api/connector/source/SourceReader.java +++ b/flink-core/src/main/java/org/apache/flink/api/connector/source/SourceReader.java @@ -63,19 +63,40 @@ public interface SourceReader<T, SplitT extends SourceSplit> List<SplitT> snapshotState(long checkpointId); /** + * Returns a future that signals that data is available from the reader. + * + * <p>Once the future completes, the runtime will keep calling the {@link #pollNext(ReaderOutput)} + * method until that methods returns a status other than {@link InputStatus#MORE_AVAILABLE}. + * After that the, the runtime will again call this method to obtain the next future. + * Once that completes, it will again call {@link #pollNext(ReaderOutput)} and so on. + * + * <p>The contract is the following: If the reader has data available, then all + * futures previously returned by this method must eventually complete. Otherwise + * the source might stall indefinitely. + * + * <p>It is not a problem to have occasional "false positives", meaning to complete + * a future even if no data is available. However, one should not use an "always complete" + * future in cases no data is available, because that will result in busy waiting loops + * calling {@code pollNext(...)} even though no data is available. + * * @return a future that will be completed once there is a record available to poll. */ CompletableFuture<Void> isAvailable(); /** * Adds a list of splits for this reader to read. + * This method is called when the enumerator assigns a split via + * {@link SplitEnumeratorContext#assignSplit(SourceSplit, int)} or + * {@link SplitEnumeratorContext#assignSplits(SplitsAssignment)}. * * @param splits The splits assigned by the split enumerator. */ void addSplits(List<SplitT> splits); /** - * Handle a source event sent by the {@link SplitEnumerator}. + * Handle a custom source event sent by the {@link SplitEnumerator}. + * This method is called when the enumerator sends an event via + * {@link SplitEnumeratorContext#sendEventToSourceReader(int, SourceEvent)}. * * @param sourceEvent the event sent by the {@link SplitEnumerator}. */
