Home | History | Annotate | Download | only in include 
      1 /*
      2  *  Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
      3  *
      4  *  Use of this source code is governed by a BSD-style license
      5  *  that can be found in the LICENSE file in the root of the source
      6  *  tree. An additional intellectual property rights grant can be found
      7  *  in the file PATENTS.  All contributing project authors may
      8  *  be found in the AUTHORS file in the root of the source tree.
      9  */
     10 
     11 #ifndef WEBRTC_MODULES_PACED_SENDER_H_
     12 #define WEBRTC_MODULES_PACED_SENDER_H_
     13 
     14 #include <list>
     15 #include <set>
     16 
     17 #include "webrtc/base/thread_annotations.h"
     18 #include "webrtc/modules/interface/module.h"
     19 #include "webrtc/system_wrappers/interface/scoped_ptr.h"
     20 #include "webrtc/typedefs.h"
     21 
     22 namespace webrtc {
     23 class Clock;
     24 class CriticalSectionWrapper;
     25 
     26 namespace paced_sender {
     27 class IntervalBudget;
     28 struct Packet;
     29 class PacketList;
     30 }  // namespace paced_sender
     31 
     32 class PacedSender : public Module {
     33  public:
     34   enum Priority {
     35     kHighPriority = 0,  // Pass through; will be sent immediately.
     36     kNormalPriority = 2,  // Put in back of the line.
     37     kLowPriority = 3,  // Put in back of the low priority line.
     38   };
     39   // Low priority packets are mixed with the normal priority packets
     40   // while we are paused.
     41 
     42   class Callback {
     43    public:
     44     // Note: packets sent as a result of a callback should not pass by this
     45     // module again.
     46     // Called when it's time to send a queued packet.
     47     // Returns false if packet cannot be sent.
     48     virtual bool TimeToSendPacket(uint32_t ssrc,
     49                                   uint16_t sequence_number,
     50                                   int64_t capture_time_ms,
     51                                   bool retransmission) = 0;
     52     // Called when it's a good time to send a padding data.
     53     // Returns the number of bytes sent.
     54     virtual int TimeToSendPadding(int bytes) = 0;
     55 
     56    protected:
     57     virtual ~Callback() {}
     58   };
     59 
     60   static const int kDefaultMaxQueueLengthMs = 2000;
     61   // Pace in kbits/s until we receive first estimate.
     62   static const int kDefaultInitialPaceKbps = 2000;
     63   // Pacing-rate relative to our target send rate.
     64   // Multiplicative factor that is applied to the target bitrate to calculate
     65   // the number of bytes that can be transmitted per interval.
     66   // Increasing this factor will result in lower delays in cases of bitrate
     67   // overshoots from the encoder.
     68   static const float kDefaultPaceMultiplier;
     69 
     70   PacedSender(Clock* clock, Callback* callback, int max_bitrate_kbps,
     71               int min_bitrate_kbps);
     72 
     73   virtual ~PacedSender();
     74 
     75   // Enable/disable pacing.
     76   void SetStatus(bool enable);
     77 
     78   bool Enabled() const;
     79 
     80   // Temporarily pause all sending.
     81   void Pause();
     82 
     83   // Resume sending packets.
     84   void Resume();
     85 
     86   // Set target bitrates for the pacer. Padding packets will be utilized to
     87   // reach |min_bitrate| unless enough media packets are available.
     88   void UpdateBitrate(int max_bitrate_kbps, int min_bitrate_kbps);
     89 
     90   // Returns true if we send the packet now, else it will add the packet
     91   // information to the queue and call TimeToSendPacket when it's time to send.
     92   virtual bool SendPacket(Priority priority,
     93                           uint32_t ssrc,
     94                           uint16_t sequence_number,
     95                           int64_t capture_time_ms,
     96                           int bytes,
     97                           bool retransmission);
     98 
     99   // Sets the max length of the pacer queue in milliseconds.
    100   // A negative queue size is interpreted as infinite.
    101   virtual void set_max_queue_length_ms(int max_queue_length_ms);
    102 
    103   // Returns the time since the oldest queued packet was enqueued.
    104   virtual int QueueInMs() const;
    105 
    106   // Returns the number of milliseconds until the module want a worker thread
    107   // to call Process.
    108   virtual int32_t TimeUntilNextProcess() OVERRIDE;
    109 
    110   // Process any pending packets in the queue(s).
    111   virtual int32_t Process() OVERRIDE;
    112 
    113  private:
    114   // Return true if next packet in line should be transmitted.
    115   // Return packet list that contains the next packet.
    116   bool ShouldSendNextPacket(paced_sender::PacketList** packet_list)
    117       EXCLUSIVE_LOCKS_REQUIRED(critsect_);
    118 
    119   // Local helper function to GetNextPacket.
    120   paced_sender::Packet GetNextPacketFromList(paced_sender::PacketList* packets)
    121       EXCLUSIVE_LOCKS_REQUIRED(critsect_);
    122 
    123   bool SendPacketFromList(paced_sender::PacketList* packet_list)
    124       EXCLUSIVE_LOCKS_REQUIRED(critsect_);
    125 
    126   // Updates the number of bytes that can be sent for the next time interval.
    127   void UpdateBytesPerInterval(uint32_t delta_time_in_ms)
    128       EXCLUSIVE_LOCKS_REQUIRED(critsect_);
    129 
    130   // Updates the buffers with the number of bytes that we sent.
    131   void UpdateMediaBytesSent(int num_bytes) EXCLUSIVE_LOCKS_REQUIRED(critsect_);
    132 
    133   Clock* const clock_;
    134   Callback* const callback_;
    135 
    136   scoped_ptr<CriticalSectionWrapper> critsect_;
    137   bool enabled_ GUARDED_BY(critsect_);
    138   bool paused_ GUARDED_BY(critsect_);
    139   int max_queue_length_ms_ GUARDED_BY(critsect_);
    140   // This is the media budget, keeping track of how many bits of media
    141   // we can pace out during the current interval.
    142   scoped_ptr<paced_sender::IntervalBudget> media_budget_ GUARDED_BY(critsect_);
    143   // This is the padding budget, keeping track of how many bits of padding we're
    144   // allowed to send out during the current interval. This budget will be
    145   // utilized when there's no media to send.
    146   scoped_ptr<paced_sender::IntervalBudget> padding_budget_
    147       GUARDED_BY(critsect_);
    148 
    149   int64_t time_last_update_us_ GUARDED_BY(critsect_);
    150   int64_t time_last_send_us_ GUARDED_BY(critsect_);
    151   int64_t capture_time_ms_last_queued_ GUARDED_BY(critsect_);
    152   int64_t capture_time_ms_last_sent_ GUARDED_BY(critsect_);
    153 
    154   scoped_ptr<paced_sender::PacketList> high_priority_packets_
    155       GUARDED_BY(critsect_);
    156   scoped_ptr<paced_sender::PacketList> normal_priority_packets_
    157       GUARDED_BY(critsect_);
    158   scoped_ptr<paced_sender::PacketList> low_priority_packets_
    159       GUARDED_BY(critsect_);
    160 };
    161 }  // namespace webrtc
    162 #endif  // WEBRTC_MODULES_PACED_SENDER_H_
    163