src/net/quic/quic_packet_generator.h

   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.
   4 //
   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()
  10 //
  11 // The Generator's mode of operation is controlled by two conditions:
  12 //
  13 // 1) Is the Delegate writable?
  14 //
  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.
  20 //
  21 // If the Delegate is writable, then the behavior depends on the second
  22 // condition:
  23 //
  24 // 2) Is the Generator in batch mode?
  25 //
  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.
  33 //
  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.
  39 //
  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.
  44 //
  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.
  48 //
  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.
  52
  53 #ifndef NET_QUIC_QUIC_PACKET_GENERATOR_H_
  54 #define NET_QUIC_QUIC_PACKET_GENERATOR_H_
  55
  56 #include "net/quic/quic_packet_creator.h"
  57 #include "net/quic/quic_sent_packet_manager.h"
  58 #include "net/quic/quic_types.h"
  59
  60 namespace net {
  61
  62 namespace test {
  63 class QuicPacketGeneratorPeer;
  64 }  // namespace test
  65
  66 class QuicAckNotifier;
  67
  68 class NET_EXPORT_PRIVATE QuicPacketGenerator {
  69  public:
  70   class NET_EXPORT_PRIVATE DelegateInterface {
  71    public:
  72     virtual ~DelegateInterface() {}
  73     virtual bool ShouldGeneratePacket(TransmissionType transmission_type,
  74                                       HasRetransmittableData retransmittable,
  75                                       IsHandshake handshake) = 0;
  76     virtual QuicAckFrame* CreateAckFrame() = 0;
  77     virtual QuicCongestionFeedbackFrame* CreateFeedbackFrame() = 0;
  78     virtual QuicStopWaitingFrame* CreateStopWaitingFrame() = 0;
  79     // Takes ownership of |packet.packet| and |packet.retransmittable_frames|.
  80     virtual void OnSerializedPacket(const SerializedPacket& packet) = 0;
  81     virtual void CloseConnection(QuicErrorCode error, bool from_peer) = 0;
  82   };
  83
  84   // Interface which gets callbacks from the QuicPacketGenerator at interesting
  85   // points.  Implementations must not mutate the state of the generator
  86   // as a result of these callbacks.
  87   class NET_EXPORT_PRIVATE DebugDelegate {
  88    public:
  89     virtual ~DebugDelegate() {}
  90
  91     // Called when a frame has been added to the current packet.
  92     virtual void OnFrameAddedToPacket(const QuicFrame& frame) {}
  93   };
  94
  95   QuicPacketGenerator(QuicConnectionId connection_id,
  96                       QuicFramer* framer,
  97                       QuicRandom* random_generator,
  98                       DelegateInterface* delegate);
  99
 100   virtual ~QuicPacketGenerator();
 101
 102   // Called by the connection in the event of the congestion window changing.
 103   void OnCongestionWindowChange(QuicPacketCount max_packets_in_flight);
 104
 105   // Indicates that an ACK frame should be sent.  If |also_send_feedback| is
 106   // true, then it also indicates a CONGESTION_FEEDBACK frame should be sent.
 107   // If |also_send_stop_waiting| is true, then it also indicates that a
 108   // STOP_WAITING frame should be sent as well.
 109   // The contents of the frame(s) will be generated via a call to the delegates
 110   // CreateAckFrame() and CreateFeedbackFrame() when the packet is serialized.
 111   void SetShouldSendAck(bool also_send_feedback,
 112                         bool also_send_stop_waiting);
 113
 114   // Indicates that a STOP_WAITING frame should be sent.
 115   void SetShouldSendStopWaiting();
 116
 117   void AddControlFrame(const QuicFrame& frame);
 118
 119   // Given some data, may consume part or all of it and pass it to the
 120   // packet creator to be serialized into packets. If not in batch
 121   // mode, these packets will also be sent during this call. Also
 122   // attaches a QuicAckNotifier to any created stream frames, which
 123   // will be called once the frame is ACKed by the peer. The
 124   // QuicAckNotifier is owned by the QuicConnection. |notifier| may
 125   // be nullptr.
 126   QuicConsumedData ConsumeData(QuicStreamId id,
 127                                const IOVector& data,
 128                                QuicStreamOffset offset,
 129                                bool fin,
 130                                FecProtection fec_protection,
 131                                QuicAckNotifier* notifier);
 132
 133   // Indicates whether batch mode is currently enabled.
 134   bool InBatchMode();
 135   // Disables flushing.
 136   void StartBatchOperations();
 137   // Enables flushing and flushes queued data which can be sent.
 138   void FinishBatchOperations();
 139
 140   // Flushes all queued frames, even frames which are not sendable.
 141   void FlushAllQueuedFrames();
 142
 143   bool HasQueuedFrames() const;
 144
 145   // Makes the framer not serialize the protocol version in sent packets.
 146   void StopSendingVersion();
 147
 148   // Creates a version negotiation packet which supports |supported_versions|.
 149   // Caller owns the created  packet. Also, sets the entropy hash of the
 150   // serialized packet to a random bool and returns that value as a member of
 151   // SerializedPacket.
 152   QuicEncryptedPacket* SerializeVersionNegotiationPacket(
 153       const QuicVersionVector& supported_versions);
 154
 155
 156   // Re-serializes frames with the original packet's sequence number length.
 157   // Used for retransmitting packets to ensure they aren't too long.
 158   // Caller must ensure that any open FEC group is closed before calling this
 159   // method.
 160   SerializedPacket ReserializeAllFrames(
 161       const QuicFrames& frames,
 162       QuicSequenceNumberLength original_length);
 163
 164   // Update the sequence number length to use in future packets as soon as it
 165   // can be safely changed.
 166   void UpdateSequenceNumberLength(
 167       QuicPacketSequenceNumber least_packet_awaited_by_peer,
 168       QuicPacketCount max_packets_in_flight);
 169
 170   // Set the minimum number of bytes for the connection id length;
 171   void SetConnectionIdLength(uint32 length);
 172
 173   // Sets the encryption level that will be applied to new packets.
 174   void set_encryption_level(EncryptionLevel level);
 175
 176   // Sequence number of the last created packet, or 0 if no packets have been
 177   // created.
 178   QuicPacketSequenceNumber sequence_number() const;
 179
 180   size_t max_packet_length() const;
 181
 182   void set_max_packet_length(size_t length);
 183
 184   void set_debug_delegate(DebugDelegate* debug_delegate) {
 185     debug_delegate_ = debug_delegate;
 186   }
 187
 188  private:
 189   friend class test::QuicPacketGeneratorPeer;
 190
 191   // Turn on FEC protection for subsequent packets in the generator.
 192   // If no FEC group is currently open in the creator, this method flushes any
 193   // queued frames in the generator and in the creator, and it then turns FEC on
 194   // in the creator. This method may be called with an open FEC group in the
 195   // creator, in which case, only the generator's state is altered.
 196   void MaybeStartFecProtection();
 197
 198   // Serializes and calls the delegate on an FEC packet if one was under
 199   // construction in the creator. When |force| is false, it relies on the
 200   // creator being ready to send an FEC packet, otherwise FEC packet is sent
 201   // as long as one is under construction in the creator. Also tries to turn
 202   // off FEC protection in the creator if it's off in the generator.
 203   void MaybeSendFecPacketAndCloseGroup(bool force);
 204
 205   void SendQueuedFrames(bool flush);
 206
 207   // Test to see if we have pending ack, feedback, or control frames.
 208   bool HasPendingFrames() const;
 209   // Test to see if the addition of a pending frame (which might be
 210   // retransmittable) would still allow the resulting packet to be sent now.
 211   bool CanSendWithNextPendingFrameAddition() const;
 212   // Add exactly one pending frame, preferring ack over feedback over control
 213   // frames.
 214   bool AddNextPendingFrame();
 215
 216   bool AddFrame(const QuicFrame& frame);
 217
 218   void SerializeAndSendPacket();
 219
 220   DelegateInterface* delegate_;
 221   DebugDelegate* debug_delegate_;
 222
 223   QuicPacketCreator packet_creator_;
 224   QuicFrames queued_control_frames_;
 225
 226   // True if batch mode is currently enabled.
 227   bool batch_mode_;
 228
 229   // True if FEC protection is on. The creator may have an open FEC group even
 230   // if this variable is false.
 231   bool should_fec_protect_;
 232
 233   // Flags to indicate the need for just-in-time construction of a frame.
 234   bool should_send_ack_;
 235   bool should_send_feedback_;
 236   bool should_send_stop_waiting_;
 237   // If we put a non-retransmittable frame (namley ack or feedback frame) in
 238   // this packet, then we have to hold a reference to it until we flush (and
 239   // serialize it). Retransmittable frames are referenced elsewhere so that they
 240   // can later be (optionally) retransmitted.
 241   scoped_ptr<QuicAckFrame> pending_ack_frame_;
 242   scoped_ptr<QuicCongestionFeedbackFrame> pending_feedback_frame_;
 243   scoped_ptr<QuicStopWaitingFrame> pending_stop_waiting_frame_;
 244
 245   DISALLOW_COPY_AND_ASSIGN(QuicPacketGenerator);
 246 };
 247
 248 }  // namespace net
 249
 250 #endif  // NET_QUIC_QUIC_PACKET_GENERATOR_H_