lollipop-counter.h

Go to the documentation of this file.

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) 2020 Universita' di Firenze, Italy
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation;
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * Author: Tommaso Pecorella <tommaso.pecorella@unifi.it>
 */


#ifndef LOLLIPOP_COUNTER_H
#define LOLLIPOP_COUNTER_H

#include <limits>
#include "ns3/abort.h"

namespace ns3 {

template <class T>
class LollipopCounter
{
public:
  LollipopCounter ()
  {
    NS_ABORT_MSG_UNLESS (std::is_unsigned<T>::value, "Lollipop counters must be defined on unsigned integer types");

    uint16_t numberofDigits = std::numeric_limits<T>::digits;
    m_sequenceWindow = 1 << (numberofDigits / 2);

    m_value = (m_maxValue - m_sequenceWindow) + 1;
  }

  LollipopCounter (T val)
  {
    uint16_t numberofDigits = std::numeric_limits<T>::digits;
    m_sequenceWindow = 1 << (numberofDigits / 2);

    m_value = val;
  }

  inline LollipopCounter & operator = (const LollipopCounter & o)
  {
    m_value = o.m_value;
    return *this;
  }

  void Reset ()
  {
    m_value = (m_maxValue - m_sequenceWindow) + 1;
  }

  void SetSequenceWindowSize (uint16_t numberOfBits)
  {
    uint16_t numberofDigits = std::numeric_limits<T>::digits;

    NS_ABORT_MSG_IF (numberOfBits >= numberofDigits, "The size of the Sequence Window should be less than the counter size (which is " << +m_maxValue << ")");

    m_sequenceWindow = 1 << numberOfBits;

    m_value = (m_maxValue - m_sequenceWindow) + 1;
  }

  bool IsComparable (const LollipopCounter &val) const
  {
    NS_ABORT_MSG_IF (m_sequenceWindow != val.m_sequenceWindow, "Can not compare two Lollipop Counters with different sequence windows");

    if ( (m_value <= m_circularRegion && val.m_value <= m_circularRegion)
         || (m_value > m_circularRegion && val.m_value > m_circularRegion) )
      {
        // They are desynchronized - comparison is impossible.
        T absDiff = AbsoluteMagnitudeOfDifference (val);
        if (absDiff > m_sequenceWindow)
          {
            return false;
          }
      }
    return true;
  }

  bool IsInit () const
  {
    if ( m_value > m_circularRegion )
      {
        return true;
      }
    return false;
  }

  friend bool operator == (const LollipopCounter & lhs, const LollipopCounter & rhs)
  {

    NS_ABORT_MSG_IF (lhs.m_sequenceWindow != rhs.m_sequenceWindow, "Can not compare two Lollipop Counters with different sequence windows");

    if (lhs.m_value == rhs.m_value)
      {
        return true;
      }
    return false;
  }

  friend bool operator > (const LollipopCounter & lhs, const LollipopCounter & rhs)
  {
    NS_ABORT_MSG_IF (lhs.m_sequenceWindow != rhs.m_sequenceWindow, "Can not compare two Lollipop Counters with different sequence windows");

    if (lhs.m_value == rhs.m_value)
      {
        return false;
      }

    if ((lhs.m_value <= m_circularRegion && rhs.m_value <= m_circularRegion)
        || (lhs.m_value > m_circularRegion && rhs.m_value > m_circularRegion) )
      {
        // both counters are in the same region

        T absDiff = lhs.AbsoluteMagnitudeOfDifference (rhs);
        if (absDiff > lhs.m_sequenceWindow)
          {
            // They are desynchronized - comparison is impossible.
            // return false because we can not return anything else.
            return false;
          }

        // They are synchronized - comparison according to RFC1982.
        T serialRegion = ((m_circularRegion >> 1) + 1);
        return (((lhs.m_value < rhs.m_value) && ((rhs.m_value - lhs.m_value) > serialRegion))
                || ((lhs.m_value > rhs.m_value) && ((lhs.m_value - rhs.m_value) < serialRegion)) );
      }

    // One counter is in the "high" region and the other is in the in the "lower" region
    bool lhsIsHigher;
    T difference;

    if (lhs.m_value > m_circularRegion && rhs.m_value <= m_circularRegion)
      {
        lhsIsHigher = true;
        // this is guaranteed to be positive and between [1...m_lollipopMaxValue].
        difference = lhs.m_value - rhs.m_value;
      }
    else
      {
        lhsIsHigher = false;
        // this is guaranteed to be positive and between [1...m_lollipopMaxValue].
        difference = rhs.m_value - lhs.m_value;
      }

    T distance = (m_maxValue - difference) + 1; // this is guaranteed to be positive and between [1...m_lollipopMaxValue].
    if (distance > lhs.m_sequenceWindow)
      {
        if (lhsIsHigher)
          {
            return true;
          }
        else
          {
            return false;
          }
      }
    else
      {
        if (lhsIsHigher)
          {
            return false;
          }
        else
          {
            return true;
          }
      }

    // this should never be reached.
    return false;
  }

  friend bool operator < (const LollipopCounter & lhs, const LollipopCounter & rhs)
  {
    if (!lhs.IsComparable (rhs))
      {
        return false;
      }

    if (lhs > rhs)
      {
        return false;
      }
    else if (lhs == rhs)
      {
        return false;
      }

    return true;
  }

  friend LollipopCounter operator++ (LollipopCounter& val)   // prefix ++
  {
    val.m_value++;

    if ( val.m_value == val.m_circularRegion + 1 )
      {
        val.m_value = 0;
      }

    return val;
  }

  friend LollipopCounter operator++ (LollipopCounter& val, int noop)  // postfix ++
  {
    LollipopCounter ans = val;
    ++(val);  // or just call operator++()
    return ans;
  }

  T GetValue () const
  {
    return m_value;
  }

  friend std::ostream &
  operator<< (std::ostream & os, LollipopCounter const & counter)
  {
    os << +counter.m_value;
    return os;
  }

private:

  T AbsoluteMagnitudeOfDifference (LollipopCounter const & val) const
  {
    // useless because it is computed always on counters on their respective regions.
    // Left (commented) for debugging purposes in case there is a code change.
    // NS_ASSERT_MSG ((m_value <= m_circularRegion && val.m_value <= m_circularRegion) ||
    //                (m_value > m_circularRegion && val.m_value > m_circularRegion),
    //                "Absolute Magnitude Of Difference can be computed only on two values in the circular region " << +m_value << " - " << +val.m_value);

    T absDiffDirect = std::max (m_value, val.m_value) - std::min (m_value, val.m_value);
    T absDiffWrapped = (std::min (m_value, val.m_value) + m_circularRegion + 1) - std::max (m_value, val.m_value);
    T absDiff = std::min (absDiffDirect, absDiffWrapped);
    return absDiff;
  }

  T m_value;          
  T m_sequenceWindow; 
  static constexpr T m_maxValue = std::numeric_limits<T>::max ();  
  static constexpr T m_circularRegion = m_maxValue >> 1;           
};

typedef LollipopCounter<uint8_t> LollipopCounter8;
typedef LollipopCounter<uint16_t> LollipopCounter16;

} /* namespace ns3 */

#endif /* LOLLIPOP_COUNTER_H */