io.vertx.core.streams.Pump Maven / Gradle / Ivy
/*
* Copyright (c) 2011-2019 Contributors to the Eclipse Foundation
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
* which is available at https://www.apache.org/licenses/LICENSE-2.0.
*
* SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
*/
package io.vertx.core.streams;
import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.streams.impl.PumpImpl;
/**
* Pumps data from a {@link ReadStream} to a {@link WriteStream} and performs flow control where necessary to
* prevent the write stream buffer from getting overfull.
*
* Instances of this class read items from a {@link ReadStream} and write them to a {@link WriteStream}. If data
* can be read faster than it can be written this could result in the write queue of the {@link WriteStream} growing
* without bound, eventually causing it to exhaust all available RAM.
*
* To prevent this, after each write, instances of this class check whether the write queue of the {@link
* WriteStream} is full, and if so, the {@link ReadStream} is paused, and a {@code drainHandler} is set on the
* {@link WriteStream}.
*
* When the {@link WriteStream} has processed half of its backlog, the {@code drainHandler} will be
* called, which results in the pump resuming the {@link ReadStream}.
*
* This class can be used to pump from any {@link ReadStream} to any {@link WriteStream},
* e.g. from an {@link io.vertx.core.http.HttpServerRequest} to an {@link io.vertx.core.file.AsyncFile},
* or from {@link io.vertx.core.net.NetSocket} to a {@link io.vertx.core.http.WebSocket}.
*
* Please see the documentation for more information.
*
* @author Tim Fox
* @deprecated instead use {@link ReadStream#pipe()} or {@link ReadStream#pipeTo(WriteStream)}
*/
@Deprecated
@VertxGen
public interface Pump {
/**
* Create a new {@code Pump} with the given {@code ReadStream} and {@code WriteStream}
*
* @param rs the read stream
* @param ws the write stream
* @return the pump
*/
static Pump pump(ReadStream rs, WriteStream ws) {
return new PumpImpl<>(rs, ws);
}
/**
* Create a new {@code Pump} with the given {@code ReadStream} and {@code WriteStream} and
* {@code writeQueueMaxSize}
*
* @param rs the read stream
* @param ws the write stream
* @param writeQueueMaxSize the max size of the write queue
* @return the pump
*/
static Pump pump(ReadStream rs, WriteStream ws, int writeQueueMaxSize) {
return new PumpImpl<>(rs, ws, writeQueueMaxSize);
}
/**
* Set the write queue max size to {@code maxSize}
*
* @param maxSize the max size
* @return a reference to this, so the API can be used fluently
*/
@Fluent
Pump setWriteQueueMaxSize(int maxSize);
/**
* Start the Pump. The Pump can be started and stopped multiple times.
*
* @return a reference to this, so the API can be used fluently
*/
@Fluent
Pump start();
/**
* Stop the Pump. The Pump can be started and stopped multiple times.
*
* @return a reference to this, so the API can be used fluently
*/
@Fluent
Pump stop();
/**
* Return the total number of items pumped by this pump.
*/
int numberPumped();
}