src/java/org/apache/cassandra/streaming/StreamingDataOutputPlus.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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 org.apache.cassandra.streaming;

import java.io.Closeable;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.channels.FileChannel;

import io.netty.channel.FileRegion;
import org.apache.cassandra.io.util.DataOutputPlus;
import org.apache.cassandra.utils.Shared;

import static org.apache.cassandra.utils.Shared.Recursive.INTERFACES;
import static org.apache.cassandra.utils.Shared.Scope.SIMULATION;

@Shared(scope = SIMULATION, inner = INTERFACES)
public interface StreamingDataOutputPlus extends DataOutputPlus, Closeable
{
    interface BufferSupplier
    {
        /**
         * Request a buffer with at least the given capacity.
         * This method may only be invoked once, and the lifetime of buffer it returns will be managed
         * by the AsyncChannelOutputPlus it was created for.
         */
        ByteBuffer get(int capacity) throws IOException;
    }

    interface Write
    {
        /**
         * Write to a buffer, and flush its contents to the channel.
         * <p>
         * The lifetime of the buffer will be managed by the AsyncChannelOutputPlus you issue this Write to.
         * If the method exits successfully, the contents of the buffer will be written to the channel, otherwise
         * the buffer will be cleaned and the exception propagated to the caller.
         */
        void write(BufferSupplier supplier) throws IOException;
    }

    interface RateLimiter
    {
        void acquire(int bytes);

        boolean isRateLimited();
    }

    /**
     * Provide a lambda that can request a buffer of suitable size, then fill the buffer and have
     * that buffer written and flushed to the underlying channel, without having to handle buffer
     * allocation, lifetime or cleanup, including in case of exceptions.
     * <p>
     * Any exception thrown by the Write will be propagated to the caller, after any buffer is cleaned up.
     */
    int writeToChannel(Write write, RateLimiter limiter) throws IOException;

    /**
     * Writes all data in file channel to stream: <br>
     * * For zero-copy-streaming, 1MiB at a time, with at most 2MiB in flight at once. <br>
     * * For streaming with SSL, 64KiB at a time, with at most 32+64KiB (default low water mark + batch size) in flight. <br>
     * <p>
     * This method takes ownership of the provided {@link FileChannel}.
     * <p>
     * WARNING: this method blocks only for permission to write to the netty channel; it exits before
     * the {@link FileRegion}(zero-copy) or {@link ByteBuffer}(ssl) is flushed to the network.
     */
    long writeFileToChannel(FileChannel file, RateLimiter limiter) throws IOException;

    default void flush() throws IOException {}
}