1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 // Responsible for generating packets on behalf of a QuicConnection.
6 // Packets are serialized just-in-time. Control frames are queued.
7 // Ack and Feedback frames will be requested from the Connection
8 // just-in-time. When a packet needs to be sent, the Generator
9 // will serialize a packet and pass it to QuicConnection::SendOrQueuePacket()
11 // The Generator's mode of operation is controlled by two conditions:
13 // 1) Is the Delegate writable?
15 // If the Delegate is not writable, then no operations will cause
16 // a packet to be serialized. In particular:
17 // * SetShouldSendAck will simply record that an ack is to be sent.
18 // * AddControlFrame will enqueue the control frame.
19 // * ConsumeData will do nothing.
21 // If the Delegate is writable, then the behavior depends on the second
24 // 2) Is the Generator in batch mode?
26 // If the Generator is NOT in batch mode, then each call to a write
27 // operation will serialize one or more packets. The contents will
28 // include any previous queued frames. If an ack should be sent
29 // but has not been sent, then the Delegate will be asked to create
30 // an Ack frame which will then be included in the packet. When
31 // the write call completes, the current packet will be serialized
32 // and sent to the Delegate, even if it is not full.
34 // If the Generator is in batch mode, then each write operation will
35 // add data to the "current" packet. When the current packet becomes
36 // full, it will be serialized and sent to the packet. When batch
37 // mode is ended via |FinishBatchOperations|, the current packet
38 // will be serialzied, even if it is not full.
40 // FEC behavior also depends on batch mode. In batch mode, FEC packets
41 // will be sent after |max_packets_per_group| have been sent, as well
42 // as after batch operations are complete. When not in batch mode,
43 // an FEC packet will be sent after each write call completes.
45 // TODO(rch): This behavior should probably be tuned. When not in batch
46 // mode, we should probably set a timer so that several independent
47 // operations can be grouped into the same FEC group.
49 // When an FEC packet is generated, it will be send to the Delegate,
50 // even if the Delegate has become unwritable after handling the
51 // data packet immediately proceeding the FEC packet.
53 #ifndef NET_QUIC_QUIC_PACKET_GENERATOR_H_
54 #define NET_QUIC_QUIC_PACKET_GENERATOR_H_
56 #include "net/quic/quic_packet_creator.h"
60 class QuicAckNotifier;
62 class NET_EXPORT_PRIVATE QuicPacketGenerator {
64 class NET_EXPORT_PRIVATE DelegateInterface {
66 virtual ~DelegateInterface() {}
67 virtual bool ShouldGeneratePacket(TransmissionType transmission_type,
68 HasRetransmittableData retransmittable,
69 IsHandshake handshake) = 0;
70 virtual QuicAckFrame* CreateAckFrame() = 0;
71 virtual QuicCongestionFeedbackFrame* CreateFeedbackFrame() = 0;
72 // Takes ownership of |packet.packet| and |packet.retransmittable_frames|.
73 virtual bool OnSerializedPacket(const SerializedPacket& packet) = 0;
74 virtual void CloseConnection(QuicErrorCode error, bool from_peer) = 0;
77 // Interface which gets callbacks from the QuicPacketGenerator at interesting
78 // points. Implementations must not mutate the state of the generator
79 // as a result of these callbacks.
80 class NET_EXPORT_PRIVATE DebugDelegateInterface {
82 virtual ~DebugDelegateInterface() {}
84 // Called when a frame has been added to the current packet.
85 virtual void OnFrameAddedToPacket(const QuicFrame& frame) = 0;
88 QuicPacketGenerator(DelegateInterface* delegate,
89 DebugDelegateInterface* debug_delegate,
90 QuicPacketCreator* creator);
92 virtual ~QuicPacketGenerator();
94 // Indicates that an ACK frame should be sent. If |also_send_feedback| is
95 // true, then it also indicates a CONGESTION_FEEDBACK frame should be sent.
96 // The contents of the frame(s) will be generated via a call to the delegates
97 // CreateAckFrame() and CreateFeedbackFrame() when the packet is serialized.
98 void SetShouldSendAck(bool also_send_feedback);
99 void AddControlFrame(const QuicFrame& frame);
101 // Given some data, may consume part or all of it and pass it to the
102 // packet creator to be serialized into packets. If not in batch
103 // mode, these packets will also be sent during this call. Also
104 // attaches a QuicAckNotifier to any created stream frames, which
105 // will be called once the frame is ACKed by the peer. The
106 // QuicAckNotifier is owned by the QuicConnection. |notifier| may
108 QuicConsumedData ConsumeData(QuicStreamId id,
109 base::StringPiece data,
110 QuicStreamOffset offset,
112 QuicAckNotifier* notifier);
114 // Indicates whether batch mode is currently enabled.
116 // Disables flushing.
117 void StartBatchOperations();
118 // Enables flushing and flushes queued data which can be sent.
119 void FinishBatchOperations();
121 // Flushes all queued frames, even frames which are not sendable.
122 void FlushAllQueuedFrames();
124 bool HasQueuedFrames() const;
126 void set_debug_delegate(DebugDelegateInterface* debug_delegate) {
127 debug_delegate_ = debug_delegate;
131 void SendQueuedFrames(bool flush);
133 // Test to see if we have pending ack, feedback, or control frames.
134 bool HasPendingFrames() const;
135 // Test to see if the addition of a pending frame (which might be
136 // retransmittable) would still allow the resulting packet to be sent now.
137 bool CanSendWithNextPendingFrameAddition() const;
138 // Add exactly one pending frame, preferring ack over feedback over control
140 bool AddNextPendingFrame();
142 bool AddFrame(const QuicFrame& frame);
144 void SerializeAndSendPacket();
146 DelegateInterface* delegate_;
147 DebugDelegateInterface* debug_delegate_;
149 QuicPacketCreator* packet_creator_;
150 QuicFrames queued_control_frames_;
152 // True if batch mode is currently enabled.
155 // Flags to indicate the need for just-in-time construction of a frame.
156 bool should_send_ack_;
157 bool should_send_feedback_;
158 // If we put a non-retransmittable frame (namley ack or feedback frame) in
159 // this packet, then we have to hold a reference to it until we flush (and
160 // serialize it). Retransmittable frames are referenced elsewhere so that they
161 // can later be (optionally) retransmitted.
162 scoped_ptr<QuicAckFrame> pending_ack_frame_;
163 scoped_ptr<QuicCongestionFeedbackFrame> pending_feedback_frame_;
165 DISALLOW_COPY_AND_ASSIGN(QuicPacketGenerator);
170 #endif // NET_QUIC_QUIC_PACKET_GENERATOR_H_