2015-01-20 01:48:11 +01:00
|
|
|
/*
|
|
|
|
* Copyright 2014 The Netty Project
|
|
|
|
*
|
|
|
|
* The Netty Project 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 io.netty.handler.codec.http2;
|
|
|
|
|
|
|
|
import io.netty.channel.ChannelHandlerContext;
|
2016-04-12 14:22:41 +02:00
|
|
|
import io.netty.util.internal.UnstableApi;
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* A {@link Http2FlowController} for controlling the flow of outbound {@code DATA} frames to the remote
|
|
|
|
* endpoint.
|
|
|
|
*/
|
2016-04-12 14:22:41 +02:00
|
|
|
@UnstableApi
|
2015-01-20 01:48:11 +01:00
|
|
|
public interface Http2RemoteFlowController extends Http2FlowController {
|
2015-06-30 19:10:17 +02:00
|
|
|
/**
|
|
|
|
* Get the {@link ChannelHandlerContext} for which to apply flow control on.
|
|
|
|
* <p>
|
|
|
|
* This is intended for us by {@link FlowControlled} implementations only. Use with caution.
|
|
|
|
* @return The {@link ChannelHandlerContext} for which to apply flow control on.
|
|
|
|
*/
|
|
|
|
ChannelHandlerContext channelHandlerContext();
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
2015-06-04 20:55:18 +02:00
|
|
|
* Queues a payload for transmission to the remote endpoint. There is no guarantee as to when the data
|
2015-09-21 23:09:06 +02:00
|
|
|
* will be written or how it will be assigned to frames.
|
2015-01-23 20:32:17 +01:00
|
|
|
* before sending.
|
2015-01-20 01:48:11 +01:00
|
|
|
* <p>
|
2015-06-04 20:55:18 +02:00
|
|
|
* Writes do not actually occur until {@link #writePendingBytes()} is called.
|
2015-01-20 01:48:11 +01:00
|
|
|
*
|
|
|
|
* @param stream the subject stream. Must not be the connection stream object.
|
2015-01-23 20:32:17 +01:00
|
|
|
* @param payload payload to write subject to flow-control accounting and ordering rules.
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
2015-06-30 19:10:17 +02:00
|
|
|
void addFlowControlled(Http2Stream stream, FlowControlled payload);
|
2015-06-04 20:55:18 +02:00
|
|
|
|
2016-01-29 09:45:12 +01:00
|
|
|
/**
|
|
|
|
* Determine if {@code stream} has any {@link FlowControlled} frames currently queued.
|
|
|
|
* @param stream the stream to check if it has flow controlled frames.
|
|
|
|
* @return {@code true} if {@code stream} has any {@link FlowControlled} frames currently queued.
|
|
|
|
*/
|
|
|
|
boolean hasFlowControlled(Http2Stream stream);
|
|
|
|
|
2015-06-04 20:55:18 +02:00
|
|
|
/**
|
|
|
|
* Write all data pending in the flow controller up to the flow-control limits.
|
|
|
|
*
|
|
|
|
* @throws Http2Exception throws if a protocol-related error occurred.
|
|
|
|
*/
|
|
|
|
void writePendingBytes() throws Http2Exception;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Set the active listener on the flow-controller.
|
|
|
|
*
|
|
|
|
* @param listener to notify when the a write occurs, can be {@code null}.
|
|
|
|
*/
|
|
|
|
void listener(Listener listener);
|
|
|
|
|
|
|
|
/**
|
2015-09-26 00:49:05 +02:00
|
|
|
* Determine if the {@code stream} has bytes remaining for use in the flow control window.
|
|
|
|
* <p>
|
|
|
|
* Note that this only takes into account HTTP/2 flow control. It does <strong>not</strong> take into account
|
|
|
|
* the underlying {@link io.netty.channel.Channel#isWritable()}.
|
|
|
|
* @param stream The stream to test.
|
|
|
|
* @return {@code true} if if the {@code stream} has bytes remaining for use in the flow control window.
|
|
|
|
* {@code false} otherwise.
|
|
|
|
*/
|
|
|
|
boolean isWritable(Http2Stream stream);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Notification that the writability of {@link #channelHandlerContext()} has changed.
|
|
|
|
* @throws Http2Exception If any writes occur as a result of this call and encounter errors.
|
2015-06-04 20:55:18 +02:00
|
|
|
*/
|
2015-09-26 00:49:05 +02:00
|
|
|
void channelWritabilityChanged() throws Http2Exception;
|
2015-01-20 01:48:11 +01:00
|
|
|
|
|
|
|
/**
|
2015-01-23 20:32:17 +01:00
|
|
|
* Implementations of this interface are used to progressively write chunks of the underlying
|
|
|
|
* payload to the stream. A payload is considered to be fully written if {@link #write} has
|
|
|
|
* been called at least once and it's {@link #size} is now zero.
|
2015-01-20 01:48:11 +01:00
|
|
|
*/
|
2015-01-23 20:32:17 +01:00
|
|
|
interface FlowControlled {
|
|
|
|
/**
|
|
|
|
* The size of the payload in terms of bytes applied to the flow-control window.
|
|
|
|
* Some payloads like {@code HEADER} frames have no cost against flow control and would
|
|
|
|
* return 0 for this value even though they produce a non-zero number of bytes on
|
|
|
|
* the wire. Other frames like {@code DATA} frames have both their payload and padding count
|
|
|
|
* against flow-control.
|
|
|
|
*/
|
|
|
|
int size();
|
|
|
|
|
|
|
|
/**
|
2015-03-05 00:55:55 +01:00
|
|
|
* Called to indicate that an error occurred before this object could be completely written.
|
|
|
|
* <p>
|
2015-10-30 17:14:52 +01:00
|
|
|
* The {@link Http2RemoteFlowController} will make exactly one call to either
|
|
|
|
* this method or {@link #writeComplete()}.
|
2015-03-05 00:55:55 +01:00
|
|
|
* </p>
|
|
|
|
*
|
2015-06-30 19:10:17 +02:00
|
|
|
* @param ctx The context to use if any communication needs to occur as a result of the error.
|
|
|
|
* This may be {@code null} if an exception occurs when the connection has not been established yet.
|
2015-01-23 20:32:17 +01:00
|
|
|
* @param cause of the error.
|
|
|
|
*/
|
2015-06-30 19:10:17 +02:00
|
|
|
void error(ChannelHandlerContext ctx, Throwable cause);
|
2015-01-23 20:32:17 +01:00
|
|
|
|
2015-03-05 00:55:55 +01:00
|
|
|
/**
|
|
|
|
* Called after this object has been successfully written.
|
|
|
|
* <p>
|
2015-10-30 17:14:52 +01:00
|
|
|
* The {@link Http2RemoteFlowController} will make exactly one call to either
|
|
|
|
* this method or {@link #error(ChannelHandlerContext, Throwable)}.
|
2015-03-05 00:55:55 +01:00
|
|
|
* </p>
|
|
|
|
*/
|
|
|
|
void writeComplete();
|
|
|
|
|
2015-01-23 20:32:17 +01:00
|
|
|
/**
|
|
|
|
* Writes up to {@code allowedBytes} of the encapsulated payload to the stream. Note that
|
|
|
|
* a value of 0 may be passed which will allow payloads with flow-control size == 0 to be
|
|
|
|
* written. The flow-controller may call this method multiple times with different values until
|
2015-04-23 23:23:23 +02:00
|
|
|
* the payload is fully written, i.e it's size after the write is 0.
|
2015-03-05 00:55:55 +01:00
|
|
|
* <p>
|
|
|
|
* When an exception is thrown the {@link Http2RemoteFlowController} will make a call to
|
2015-10-30 17:14:52 +01:00
|
|
|
* {@link #error(ChannelHandlerContext, Throwable)}.
|
2015-03-05 00:55:55 +01:00
|
|
|
* </p>
|
2015-01-23 20:32:17 +01:00
|
|
|
*
|
2015-06-30 19:10:17 +02:00
|
|
|
* @param ctx The context to use for writing.
|
2015-01-23 20:32:17 +01:00
|
|
|
* @param allowedBytes an upper bound on the number of bytes the payload can write at this time.
|
|
|
|
*/
|
2017-01-26 18:03:42 +01:00
|
|
|
void write(ChannelHandlerContext ctx, int allowedBytes);
|
2015-06-04 20:55:18 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Merge the contents of the {@code next} message into this message so they can be written out as one unit.
|
|
|
|
* This allows many small messages to be written as a single DATA frame.
|
|
|
|
*
|
|
|
|
* @return {@code true} if {@code next} was successfully merged and does not need to be enqueued,
|
|
|
|
* {@code false} otherwise.
|
|
|
|
*/
|
2015-06-30 19:10:17 +02:00
|
|
|
boolean merge(ChannelHandlerContext ctx, FlowControlled next);
|
2015-06-04 20:55:18 +02:00
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Listener to the number of flow-controlled bytes written per stream.
|
|
|
|
*/
|
|
|
|
interface Listener {
|
2015-09-26 00:49:05 +02:00
|
|
|
/**
|
|
|
|
* Notification that {@link Http2RemoteFlowController#isWritable(Http2Stream)} has changed for {@code stream}.
|
|
|
|
* <p>
|
|
|
|
* This method should not throw. Any thrown exceptions are considered a programming error and are ignored.
|
|
|
|
* @param stream The stream which writability has changed for.
|
|
|
|
*/
|
|
|
|
void writabilityChanged(Http2Stream stream);
|
2015-01-23 20:32:17 +01:00
|
|
|
}
|
2015-01-20 01:48:11 +01:00
|
|
|
}
|