View Javadoc
1   /*
2    * Copyright 2014 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License, version 2.0 (the
5    * "License"); you may not use this file except in compliance with the License. You may obtain a
6    * copy of the License at:
7    *
8    * http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software distributed under the License
11   * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
12   * or implied. See the License for the specific language governing permissions and limitations under
13   * the License.
14   */
15  package io.netty.handler.codec.http2;
16  
17  import io.netty.channel.ChannelHandlerContext;
18  import io.netty.util.internal.UnstableApi;
19  
20  /**
21   * A {@link Http2FlowController} for controlling the flow of outbound {@code DATA} frames to the remote
22   * endpoint.
23   */
24  @UnstableApi
25  public interface Http2RemoteFlowController extends Http2FlowController {
26      /**
27       * Get the {@link ChannelHandlerContext} for which to apply flow control on.
28       * <p>
29       * This is intended for us by {@link FlowControlled} implementations only. Use with caution.
30       * @return The {@link ChannelHandlerContext} for which to apply flow control on.
31       */
32      ChannelHandlerContext channelHandlerContext();
33  
34      /**
35       * Queues a payload for transmission to the remote endpoint. There is no guarantee as to when the data
36       * will be written or how it will be assigned to frames.
37       * before sending.
38       * <p>
39       * Writes do not actually occur until {@link #writePendingBytes()} is called.
40       *
41       * @param stream the subject stream. Must not be the connection stream object.
42       * @param payload payload to write subject to flow-control accounting and ordering rules.
43       */
44      void addFlowControlled(Http2Stream stream, FlowControlled payload);
45  
46      /**
47       * Determine if {@code stream} has any {@link FlowControlled} frames currently queued.
48       * @param stream the stream to check if it has flow controlled frames.
49       * @return {@code true} if {@code stream} has any {@link FlowControlled} frames currently queued.
50       */
51      boolean hasFlowControlled(Http2Stream stream);
52  
53      /**
54       * Write all data pending in the flow controller up to the flow-control limits.
55       *
56       * @throws Http2Exception throws if a protocol-related error occurred.
57       */
58      void writePendingBytes() throws Http2Exception;
59  
60      /**
61       * Set the active listener on the flow-controller.
62       *
63       * @param listener to notify when the a write occurs, can be {@code null}.
64       */
65      void listener(Listener listener);
66  
67      /**
68       * Determine if the {@code stream} has bytes remaining for use in the flow control window.
69       * <p>
70       * Note that this method respects channel writability. The channel must be writable for this method to
71       * return {@code true}.
72       *
73       * @param stream The stream to test.
74       * @return {@code true} if the {@code stream} has bytes remaining for use in the flow control window and the
75       * channel is writable, {@code false} otherwise.
76       */
77      boolean isWritable(Http2Stream stream);
78  
79      /**
80       * Notification that the writability of {@link #channelHandlerContext()} has changed.
81       * @throws Http2Exception If any writes occur as a result of this call and encounter errors.
82       */
83      void channelWritabilityChanged() throws Http2Exception;
84  
85      /**
86       * Explicitly update the dependency tree. This method is called independently of stream state changes.
87       * @param childStreamId The stream identifier associated with the child stream.
88       * @param parentStreamId The stream identifier associated with the parent stream. May be {@code 0},
89       *                       to make {@code childStreamId} and immediate child of the connection.
90       * @param weight The weight which is used relative to other child streams for {@code parentStreamId}. This value
91       *               must be between 1 and 256 (inclusive).
92       * @param exclusive If {@code childStreamId} should be the exclusive dependency of {@code parentStreamId}.
93       */
94      void updateDependencyTree(int childStreamId, int parentStreamId, short weight, boolean exclusive);
95  
96      /**
97       * Implementations of this interface are used to progressively write chunks of the underlying
98       * payload to the stream. A payload is considered to be fully written if {@link #write} has
99       * been called at least once and it's {@link #size} is now zero.
100      */
101     interface FlowControlled {
102         /**
103          * The size of the payload in terms of bytes applied to the flow-control window.
104          * Some payloads like {@code HEADER} frames have no cost against flow control and would
105          * return 0 for this value even though they produce a non-zero number of bytes on
106          * the wire. Other frames like {@code DATA} frames have both their payload and padding count
107          * against flow-control.
108          */
109         int size();
110 
111         /**
112          * Called to indicate that an error occurred before this object could be completely written.
113          * <p>
114          * The {@link Http2RemoteFlowController} will make exactly one call to either
115          * this method or {@link #writeComplete()}.
116          * </p>
117          *
118          * @param ctx The context to use if any communication needs to occur as a result of the error.
119          * This may be {@code null} if an exception occurs when the connection has not been established yet.
120          * @param cause of the error.
121          */
122         void error(ChannelHandlerContext ctx, Throwable cause);
123 
124         /**
125          * Called after this object has been successfully written.
126          * <p>
127          * The {@link Http2RemoteFlowController} will make exactly one call to either
128          * this method or {@link #error(ChannelHandlerContext, Throwable)}.
129          * </p>
130          */
131         void writeComplete();
132 
133         /**
134          * Writes up to {@code allowedBytes} of the encapsulated payload to the stream. Note that
135          * a value of 0 may be passed which will allow payloads with flow-control size == 0 to be
136          * written. The flow-controller may call this method multiple times with different values until
137          * the payload is fully written, i.e it's size after the write is 0.
138          * <p>
139          * When an exception is thrown the {@link Http2RemoteFlowController} will make a call to
140          * {@link #error(ChannelHandlerContext, Throwable)}.
141          * </p>
142          *
143          * @param ctx The context to use for writing.
144          * @param allowedBytes an upper bound on the number of bytes the payload can write at this time.
145          */
146         void write(ChannelHandlerContext ctx, int allowedBytes);
147 
148         /**
149          * Merge the contents of the {@code next} message into this message so they can be written out as one unit.
150          * This allows many small messages to be written as a single DATA frame.
151          *
152          * @return {@code true} if {@code next} was successfully merged and does not need to be enqueued,
153          *     {@code false} otherwise.
154          */
155         boolean merge(ChannelHandlerContext ctx, FlowControlled next);
156     }
157 
158     /**
159      * Listener to the number of flow-controlled bytes written per stream.
160      */
161     interface Listener {
162         /**
163          * Notification that {@link Http2RemoteFlowController#isWritable(Http2Stream)} has changed for {@code stream}.
164          * <p>
165          * This method should not throw. Any thrown exceptions are considered a programming error and are ignored.
166          * @param stream The stream which writability has changed for.
167          */
168         void writabilityChanged(Http2Stream stream);
169     }
170 }