io.trino.spi.exchange.Exchange Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of trino-spi Show documentation
Trino - Service Provider Interface (SPI)
The newest version!
/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.trino.spi.exchange;

import com.google.errorprone.annotations.ThreadSafe;
import io.trino.spi.Experimental;

import java.io.Closeable;
import java.util.concurrent.CompletableFuture;

@ThreadSafe
@Experimental(eta = "2024-03-01")
public interface Exchange
        extends Closeable
{
    enum SourceHandlesDeliveryMode {
        STANDARD,
        EAGER
    }

    /**
     * Get id of this exchange
     */
    ExchangeId getId();

    /**
     * Registers a new sink
     *
     * @param taskPartitionId uniquely identifies a dataset written to a sink
     * @return {@link ExchangeSinkHandle} associated with the taskPartitionId.
     * Must be passed to {@link #instantiateSink(ExchangeSinkHandle, int)} along with an attempt id to create a sink instance
     */
    ExchangeSinkHandle addSink(int taskPartitionId);

    /**
     * Called when no more sinks will be added with {@link #addSink(int)}.
     * New sink instances for an existing sink may still be added with {@link #instantiateSink(ExchangeSinkHandle, int)}.
     */
    void noMoreSinks();

    /**
     * Registers a sink instance for an attempt.
     * 
     * Attempts are expected to produce the same data.
     * 

     * The implementation must ensure the data written by unsuccessful attempts is safely discarded.
     * An attempt is considered successful when an {@link ExchangeSink} is closed with the {@link ExchangeSink#finish()} method.
     * When a node dies before {@link ExchangeSink#finish()} is called or when an {@link ExchangeSink} is closed with the
     * {@link ExchangeSink#abort()} method an attempt should be considered as unsuccessful.
     * 

     * When more than a single attempt is successful the implementation must pick one and discard the output of the other attempts
     *
     * @param sinkHandle - handle returned by addSink
     * @param taskAttemptId - attempt id
     * @return ExchangeSinkInstanceHandle to be sent to a worker that is needed to create an {@link ExchangeSink} instance using
     * {@link ExchangeManager#createSink(ExchangeSinkInstanceHandle)}
     */
    CompletableFuture instantiateSink(ExchangeSinkHandle sinkHandle, int taskAttemptId);

    /**
     * Update {@link ExchangeSinkInstanceHandle}. Update is requested by {@link ExchangeSink}.
     * The updated {@link ExchangeSinkInstanceHandle} is expected to be set by {@link ExchangeSink#updateHandle(ExchangeSinkInstanceHandle)}.
     *
     * @param sinkHandle - handle returned by addSink
     * @param taskAttemptId - attempt id
     * @return updated handle
     */
    CompletableFuture updateSinkInstanceHandle(ExchangeSinkHandle sinkHandle, int taskAttemptId);

    /**
     * Called by the engine when an attempt finishes successfully.
     * 

     * This method is expected to be lightweight. An implementation shouldn't perform any long running blocking operations within this method.
     */
    void sinkFinished(ExchangeSinkHandle sinkHandle, int taskAttemptId);

    /**
     * Called by the engine when all required sinks finished successfully.
     * While some source tasks may still be running and writing to their sinks the data written to these sinks could be safely ignored after this method is invoked.
     */
    void allRequiredSinksFinished();

    /**
     * Returns an {@link ExchangeSourceHandleSource} instance to be used to enumerate {@link ExchangeSourceHandle}s.
     *
     * @return Future containing a list of {@link ExchangeSourceHandle} to be sent to a
     * worker that is needed to create an {@link ExchangeSource} using {@link ExchangeManager#createSource()}
     */
    ExchangeSourceHandleSource getSourceHandles();

    /**
     * Change {@link ExchangeSourceHandleSource} delivery mode.
     * 

     * In {@link SourceHandlesDeliveryMode#STANDARD} mode the handles are delivered at
     * pace optimized for throughput.
     * 

     * In {@link SourceHandlesDeliveryMode#EAGER} the handles are delivered as soon as possible even if that would mean
     * each handle corresponds to smaller amount of data, which may be not optimal from throughput.
     * 

     * There are no strict constraints regarding when this method can be called. When called, the newly selected delivery mode
     * will apply to all {@link ExchangeSourceHandleSource} instances already obtained via {@link #getSourceHandles()} method.
     * As well as to those yet to be obtained.
     * 
     * Support for this method is optional and best-effort.
     */
    default void setSourceHandlesDeliveryMode(SourceHandlesDeliveryMode sourceHandlesDeliveryMode) {}

    @Override
    void close();
}