Improve Exchange interface documentation

Clarify several important contracts

core/trino-spi/src/main/java/io/trino/spi/exchange/Exchange.java

@@ -60,7 +60,9 @@ public interface Exchange
     ExchangeSinkInstanceHandle instantiateSink(ExchangeSinkHandle sinkHandle, int taskAttemptId);
 
     /**
-     * Called by the engine when an attempt finishes successfully
+     * Called by the engine when an attempt finishes successfully.
+     * <p>
+     * This method is expected to be lightweight. An implementation shouldn't perform any long running blocking operations within this method.
      */
     void sinkFinished(ExchangeSinkInstanceHandle handle);
 

core/trino-spi/src/main/java/io/trino/spi/exchange/ExchangeManager.java

@@ -79,6 +79,8 @@ public interface ExchangeManager
      * read. The full list of handles is returned by {@link Exchange#getSourceHandles}.
      * The coordinator decides what items from that list should be handled by what task and creates
      * sub-lists that are further getting sent to a worker to be read.
+     * The <code>handles</code> list may contain {@link ExchangeSourceHandle}'s created by more than
+     * a single {@link Exchange}.
      * @return {@link ExchangeSource} used by the engine to read data from an exchange
      */
     ExchangeSource createSource(List<ExchangeSourceHandle> handles);

core/trino-spi/src/main/java/io/trino/spi/exchange/ExchangeSink.java

@@ -35,8 +35,9 @@ public interface ExchangeSink
      * Appends arbitrary {@code data} to a partition specified by {@code partitionId}.
      * The engine is free to reuse the {@code data} buffer.
      * The implementation is expected to copy the buffer as it may be invalidated and recycled.
-     * If this method is invoked after {@link #finish()} or {@link #abort()} is initiated the
-     * invocation should be ignored.
+     * This method is guaranteed not to be invoked after {@link #finish()}.
+     * This method can be invoked after {@link #abort()}.
+     * If this method is invoked after {@link #abort()} the invocation should be ignored.
      */
     void add(int partitionId, Slice data);
 
@@ -50,6 +51,9 @@ public interface ExchangeSink
      * Notifies the exchange sink that no more data will be appended.
      * This method is guaranteed not to be called after {@link #abort()}.
      * This method is guaranteed not be called more than once.
+     * The {@link #abort()} method will not be called if the finish operation fails.
+     * The finish implementation is responsible for safely releasing resources in
+     * case of a failure.
      *
      * @return future that will be resolved when the finish operation either succeeds or fails
      */
@@ -59,6 +63,8 @@ public interface ExchangeSink
      * Notifies the exchange that the write operation has been aborted.
      * This method may be called when {@link #finish()} is still running. In this situation the implementation
      * is free to either cancel the finish operation and abort or let the finish operation succeed.
+     * This method may also be called when {@link #finish()} is done. In this situation the implementation
+     * is free to either ignore the call or invalidate the sink.
      * This method is guaranteed not be called more than once.
      *
      * @return future that will be resolved when the abort operation either succeeds or fails