spectrum: Add base class SpectrumTransmitFilter

src/spectrum/CMakeLists.txt

@@ -26,6 +26,7 @@ set(source_files
     model/spectrum-model.cc
     model/spectrum-phy.cc
     model/spectrum-propagation-loss-model.cc
+    model/spectrum-transmit-filter.cc
     model/phased-array-spectrum-propagation-loss-model.cc
     model/spectrum-signal-parameters.cc
     model/spectrum-value.cc
@@ -65,6 +66,7 @@ set(header_files
     model/spectrum-model.h
     model/spectrum-phy.h
     model/spectrum-propagation-loss-model.h
+    model/spectrum-transmit-filter.h
     model/phased-array-spectrum-propagation-loss-model.h
     model/spectrum-signal-parameters.h
     model/spectrum-value.h

src/spectrum/model/multi-model-spectrum-channel.cc

@@ -35,6 +35,7 @@
 #include <ns3/spectrum-converter.h>
 #include <ns3/spectrum-phy.h>
 #include <ns3/spectrum-propagation-loss-model.h>
+#include <ns3/spectrum-transmit-filter.h>
 
 #include <algorithm>
 #include <iostream>
@@ -308,6 +309,11 @@ MultiModelSpectrumChannel::StartTx(Ptr<SpectrumSignalParameters> txParams)
                     }
                 }
 
+                if (m_filter && m_filter->Filter(txParams, *rxPhyIterator))
+                {
+                    continue;
+                }
+
                 NS_LOG_LOGIC("copying signal parameters " << txParams);
                 Ptr<SpectrumSignalParameters> rxParams = txParams->Copy();
                 rxParams->psd = Copy<SpectrumValue>(convertedTxPowerSpectrum);

src/spectrum/model/single-model-spectrum-channel.cc

@@ -34,6 +34,7 @@
 #include <ns3/simulator.h>
 #include <ns3/spectrum-phy.h>
 #include <ns3/spectrum-propagation-loss-model.h>
+#include <ns3/spectrum-transmit-filter.h>
 
 #include <algorithm>
 
@@ -135,6 +136,11 @@ SingleModelSpectrumChannel::StartTx(Ptr<SpectrumSignalParameters> txParams)
             }
         }
 
+        if (m_filter && m_filter->Filter(txParams, *rxPhyIterator))
+        {
+            continue;
+        }
+
         if ((*rxPhyIterator) != txParams->txPhy)
         {
             Time delay = MicroSeconds(0);

src/spectrum/model/spectrum-channel.cc

@@ -146,6 +146,18 @@ SpectrumChannel::AddPhasedArraySpectrumPropagationLossModel(
     m_phasedArraySpectrumPropagationLoss = loss;
 }
 
+void
+SpectrumChannel::AddSpectrumTransmitFilter(Ptr<SpectrumTransmitFilter> filter)
+{
+    NS_LOG_FUNCTION(this << filter);
+
+    if (m_filter)
+    {
+        filter->SetNext(m_filter);
+    }
+    m_filter = filter;
+}
+
 void
 SpectrumChannel::SetPropagationDelayModel(Ptr<PropagationDelayModel> delay)
 {

src/spectrum/model/spectrum-channel.h

@@ -30,6 +30,7 @@
 #include <ns3/spectrum-phy.h>
 #include <ns3/spectrum-propagation-loss-model.h>
 #include <ns3/spectrum-signal-parameters.h>
+#include <ns3/spectrum-transmit-filter.h>
 #include <ns3/traced-callback.h>
 
 namespace ns3
@@ -114,6 +115,16 @@ class SpectrumChannel : public Channel
      */
     Ptr<PropagationLossModel> GetPropagationLossModel();
 
+    /**
+     * Add the transmit filter to be used to filter possible signal receptions
+     * at the StartTx() time.  This method may be called multiple
+     * times to chain multiple filters together; the last filter added will
+     * be the first one used in the chain.
+     *
+     * \param filter an instance of a SpectrumTransmitFilter
+     */
+    void AddSpectrumTransmitFilter(Ptr<SpectrumTransmitFilter> filter);
+
     /**
      * Used by attached PHY instances to transmit signals on the channel
      *
@@ -237,6 +248,11 @@ class SpectrumChannel : public Channel
      * Frequency-dependent propagation loss model to be used with this channel.
      */
     Ptr<PhasedArraySpectrumPropagationLossModel> m_phasedArraySpectrumPropagationLoss;
+
+    /**
+     * Transmit filter to be used with this channel
+     */
+    Ptr<SpectrumTransmitFilter> m_filter{nullptr};
 };
 
 } // namespace ns3

src/spectrum/model/spectrum-transmit-filter.cc

@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) 2022 University of Washington
+ *
+ * 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
+ *
+ */
+
+#include "spectrum-transmit-filter.h"
+
+#include "spectrum-phy.h"
+#include "spectrum-signal-parameters.h"
+
+#include <ns3/log.h>
+
+namespace ns3
+{
+
+NS_LOG_COMPONENT_DEFINE("SpectrumTransmitFilter");
+
+NS_OBJECT_ENSURE_REGISTERED(SpectrumTransmitFilter);
+
+TypeId
+SpectrumTransmitFilter::GetTypeId()
+{
+    static TypeId tid =
+        TypeId("ns3::SpectrumTransmitFilter").SetParent<Object>().SetGroupName("Spectrum");
+    return tid;
+}
+
+SpectrumTransmitFilter::SpectrumTransmitFilter()
+{
+    NS_LOG_FUNCTION(this);
+}
+
+void
+SpectrumTransmitFilter::DoDispose()
+{
+    NS_LOG_FUNCTION(this);
+    if (m_next)
+    {
+        m_next->Dispose();
+    }
+    m_next = nullptr;
+    Object::DoDispose();
+}
+
+void
+SpectrumTransmitFilter::SetNext(Ptr<SpectrumTransmitFilter> next)
+{
+    m_next = next;
+}
+
+bool
+SpectrumTransmitFilter::Filter(Ptr<const SpectrumSignalParameters> params,
+                               Ptr<const SpectrumPhy> receiverPhy)
+{
+    NS_LOG_FUNCTION(this << params << receiverPhy);
+    bool result = DoFilter(params, receiverPhy);
+    if (result)
+    {
+        return true;
+    }
+    else if (m_next)
+    {
+        return m_next->Filter(params, receiverPhy);
+    }
+    else
+    {
+        return false;
+    }
+}
+
+} // namespace ns3

src/spectrum/model/spectrum-transmit-filter.h

@@ -0,0 +1,92 @@
+/*
+ * Copyright (c) 2022 University of Washington
+ *
+ * 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
+ */
+
+#ifndef SPECTRUM_TRANSMIT_FILTER_H
+#define SPECTRUM_TRANSMIT_FILTER_H
+
+#include <ns3/object.h>
+
+namespace ns3
+{
+
+struct SpectrumSignalParameters;
+class SpectrumPhy;
+
+/**
+ * \ingroup spectrum
+ *
+ * \brief spectrum-aware transmit filter object
+ *
+ * Interface for transmit filters that permit an early discard of signal
+ * reception before propagation loss models or receiving Phy objects have
+ * to process the signal, for performance optimization purposes.
+ *
+ */
+class SpectrumTransmitFilter : public Object
+{
+  public:
+    SpectrumTransmitFilter();
+
+    /**
+     * \brief Get the type ID.
+     * \return the object TypeId
+     */
+    static TypeId GetTypeId();
+
+    /**
+     * Add a transmit filter to be consulted next if this filter does not
+     * filter the signal
+     *
+     * \param next next transmit filter to add to the chain
+     */
+    void SetNext(Ptr<SpectrumTransmitFilter> next);
+
+    /**
+     * Evaluate whether the signal to be scheduled on the receiving Phy should
+     * instead be filtered (discarded) before being processed in this channel
+     * and on the receiving Phy.
+     *
+     * \param params the spectrum signal parameters.
+     * \param receiverPhy pointer to the receiving SpectrumPhy
+     *
+     * \return whether to perform filtering of the signal
+     */
+    bool Filter(Ptr<const SpectrumSignalParameters> params, Ptr<const SpectrumPhy> receiverPhy);
+
+  protected:
+    void DoDispose() override;
+
+  private:
+    /**
+     * Evaluate whether the signal to be scheduled on the receiving Phy should
+     * instead be filtered (discarded) before being processed in this channel
+     * and on the receiving Phy.
+     *
+     * \param params the spectrum signal parameters.
+     * \param receiverPhy pointer to the receiving SpectrumPhy
+     *
+     * \return whether to perform filtering of the signal
+     */
+    virtual bool DoFilter(Ptr<const SpectrumSignalParameters> params,
+                          Ptr<const SpectrumPhy> receiverPhy) = 0;
+
+    Ptr<SpectrumTransmitFilter> m_next{nullptr}; //!< SpectrumTransmitFilter chained to this one.
+};
+
+} // namespace ns3
+
+#endif /* SPECTRUM_TRANSMIT_FILTER_H */