diff --git a/doc/manual/source/logging.rst b/doc/manual/source/logging.rst index 1d37e3e36..3a5a1afe2 100644 --- a/doc/manual/source/logging.rst +++ b/doc/manual/source/logging.rst @@ -342,6 +342,60 @@ Adding logging to your code is very simple: 2. Add logging statements (macro calls) to your functions and function bodies. +In case you want to add logging statements to the methods of your template class +(which are defined in an header file): + +1. Invoke the ``NS_LOG_TEMPLATE_DECLARE;`` macro in the private section of + your class declaration. For instance: + + :: + + template + class Queue : public QueueBase + { + ... + private: + std::list > m_packets; //!< the items in the queue + NS_LOG_TEMPLATE_DECLARE; //!< the log component + }; + + This requires you to perform these steps for all the subclasses of your class. + +2. Invoke the ``NS_LOG_TEMPLATE_DEFINE (...);`` macro in the constructor of + your class by providing the name of a log component registered by calling + the ``NS_LOG_COMPONENT_DEFINE (...);`` macro in some module. For instance: + + :: + + template + Queue::Queue () + : NS_LOG_TEMPLATE_DEFINE ("Queue") + { + } + +3. Add logging statements (macro calls) to the methods of your class. + +In case you want to add logging statements to a static member template +(which is defined in an header file): + +1. Invoke the ``NS_LOG_STATIC_TEMPLATE_DEFINE (...);`` macro in your static + method by providing the name of a log component registered by calling + the ``NS_LOG_COMPONENT_DEFINE (...);`` macro in some module. For instance: + + :: + + template + void + NetDeviceQueue::PacketEnqueued (Ptr > queue, + Ptr ndqi, + uint8_t txq, Ptr item) + { + + NS_LOG_STATIC_TEMPLATE_DEFINE ("NetDeviceQueueInterface"); + ... + +2. Add logging statements (macro calls) to your static method. + Controlling timestamp precision ******************************* diff --git a/src/core/model/log.cc b/src/core/model/log.cc index 299d1f9e3..06a76f547 100644 --- a/src/core/model/log.cc +++ b/src/core/model/log.cc @@ -23,6 +23,7 @@ #include #include #include "assert.h" +#include #include "ns3/core-config.h" #include "fatal-error.h" @@ -130,6 +131,23 @@ LogComponent::LogComponent (const std::string & name, components->insert (std::make_pair (name, this)); } +LogComponent & +GetLogComponent (const std::string name) +{ + LogComponent::ComponentList *components = LogComponent::GetComponentList (); + LogComponent* ret; + + try + { + ret = components->at (name); + } + catch (std::out_of_range&) + { + NS_FATAL_ERROR ("Log component \"" << name << "\" does not exist."); + } + return *ret; +} + void LogComponent::EnvVarCheck (void) { diff --git a/src/core/model/log.h b/src/core/model/log.h index b2b2de9bd..cab4a8372 100644 --- a/src/core/model/log.h +++ b/src/core/model/log.h @@ -212,6 +212,39 @@ void LogComponentDisableAll (enum LogLevel level); #define NS_LOG_COMPONENT_DEFINE_MASK(name, mask) \ static ns3::LogComponent g_log = ns3::LogComponent (name, __FILE__, mask) +/** + * Declare a reference to a Log component. + * + * This macro should be used in the declaration of template classes + * to allow their methods (defined in an header file) to make use of + * the NS_LOG_* macros. This macro should be used in the private + * section to prevent subclasses from using the same log component + * as the base class. + */ +#define NS_LOG_TEMPLATE_DECLARE LogComponent & g_log + +/** + * Initialize a reference to a Log component. + * + * This macro should be used in the constructor of template classes + * to allow their methods (defined in an header file) to make use of + * the NS_LOG_* macros. + * + * \param [in] name The log component name. + */ +#define NS_LOG_TEMPLATE_DEFINE(name) g_log (GetLogComponent (name)) + +/** + * Declare and initialize a reference to a Log component. + * + * This macro should be used in static template methods to allow their + * methods (defined in an header file) to make use of the NS_LOG_* macros. + * + * \param [in] name The log component name. + */ +#define NS_LOG_STATIC_TEMPLATE_DEFINE(name) \ + static LogComponent & g_log = GetLogComponent (name) + /** * Use \ref NS_LOG to output a message of level LOG_ERROR. * @@ -409,7 +442,14 @@ private: }; // class LogComponent - +/** + * Get the LogComponent registered with the given name. + * + * \param [in] name The name of the LogComponent. + * \return a reference to the requested LogComponent + */ +LogComponent & GetLogComponent (const std::string name); + /** * Insert `, ` when streaming function arguments. */ diff --git a/src/network/utils/drop-tail-queue.cc b/src/network/utils/drop-tail-queue.cc index ef417e81a..a5db143c2 100644 --- a/src/network/utils/drop-tail-queue.cc +++ b/src/network/utils/drop-tail-queue.cc @@ -20,6 +20,8 @@ namespace ns3 { +NS_LOG_COMPONENT_DEFINE ("DropTailQueue"); + NS_OBJECT_TEMPLATE_CLASS_DEFINE (DropTailQueue,Packet); } // namespace ns3 diff --git a/src/network/utils/drop-tail-queue.h b/src/network/utils/drop-tail-queue.h index 51d65a9ec..f2cee28e5 100644 --- a/src/network/utils/drop-tail-queue.h +++ b/src/network/utils/drop-tail-queue.h @@ -58,6 +58,8 @@ private: using Queue::DoDequeue; using Queue::DoRemove; using Queue::DoPeek; + + NS_LOG_TEMPLATE_DECLARE; //!< redefinition of the log component }; @@ -79,22 +81,23 @@ DropTailQueue::GetTypeId (void) template DropTailQueue::DropTailQueue () : - Queue () + Queue (), + NS_LOG_TEMPLATE_DEFINE ("DropTailQueue") { - QUEUE_LOG (LOG_LOGIC, "DropTailQueue(" << this << ")"); + NS_LOG_FUNCTION (this); } template DropTailQueue::~DropTailQueue () { - QUEUE_LOG (LOG_LOGIC, "~DropTailQueue(" << this << ")"); + NS_LOG_FUNCTION (this); } template bool DropTailQueue::Enqueue (Ptr item) { - QUEUE_LOG (LOG_LOGIC, "DropTailQueue:Enqueue(" << this << ", " << item << ")"); + NS_LOG_FUNCTION (this << item); return DoEnqueue (Tail (), item); } @@ -103,11 +106,11 @@ template Ptr DropTailQueue::Dequeue (void) { - QUEUE_LOG (LOG_LOGIC, "DropTailQueue:Dequeue(" << this << ")"); + NS_LOG_FUNCTION (this); Ptr item = DoDequeue (Head ()); - QUEUE_LOG (LOG_LOGIC, "Popped " << item); + NS_LOG_LOGIC ("Popped " << item); return item; } @@ -116,11 +119,11 @@ template Ptr DropTailQueue::Remove (void) { - QUEUE_LOG (LOG_LOGIC, "DropTailQueue:Remove(" << this << ")"); + NS_LOG_FUNCTION (this); Ptr item = DoRemove (Head ()); - QUEUE_LOG (LOG_LOGIC, "Removed " << item); + NS_LOG_LOGIC ("Removed " << item); return item; } @@ -129,7 +132,7 @@ template Ptr DropTailQueue::Peek (void) const { - QUEUE_LOG (LOG_LOGIC, "DropTailQueue:Peek(" << this << ")"); + NS_LOG_FUNCTION (this); return DoPeek (Head ()); } diff --git a/src/network/utils/net-device-queue-interface.cc b/src/network/utils/net-device-queue-interface.cc index 699021fa2..2c09e1298 100644 --- a/src/network/utils/net-device-queue-interface.cc +++ b/src/network/utils/net-device-queue-interface.cc @@ -145,12 +145,6 @@ NetDeviceQueue::GetQueueLimits () return m_queueLimits; } -void -NetDeviceQueue::DoNsLog (const enum LogLevel level, std::string str) -{ - NS_LOG (level, str); -} - NS_OBJECT_ENSURE_REGISTERED (NetDeviceQueueInterface); diff --git a/src/network/utils/net-device-queue-interface.h b/src/network/utils/net-device-queue-interface.h index 274ba2c71..37258b016 100644 --- a/src/network/utils/net-device-queue-interface.h +++ b/src/network/utils/net-device-queue-interface.h @@ -193,14 +193,6 @@ public: uint8_t txq, Ptr item); private: - /** - * \brief Pass messages to the ns-3 logging system - * - * \param level the log level - * \param str the message to log - */ - static void DoNsLog (const enum LogLevel level, std::string str); - bool m_stoppedByDevice; //!< True if the queue has been stopped by the device bool m_stoppedByQueueLimits; //!< True if the queue has been stopped by a queue limits object Ptr m_queueLimits; //!< Queue limits object @@ -338,14 +330,6 @@ private: }; -#define NDQI_LOG(level,params) \ - { \ - std::stringstream ss; \ - ss << params; \ - DoNsLog (level, ss.str ()); \ - } - - /** * Implementation of the templates declared above. */ @@ -374,8 +358,9 @@ NetDeviceQueue::PacketEnqueued (Ptr > queue, Ptr ndqi, uint8_t txq, Ptr item) { - NDQI_LOG (LOG_LOGIC, "NetDeviceQueue:PacketEnqueued(" << queue << ", " << ndqi - << ", " << txq << ", " << item << ")"); + NS_LOG_STATIC_TEMPLATE_DEFINE ("NetDeviceQueueInterface"); + + NS_LOG_FUNCTION (queue << ndqi << txq << item); // Inform BQL ndqi->GetTxQueue (txq)->NotifyQueuedBytes (item->GetSize ()); @@ -390,8 +375,8 @@ NetDeviceQueue::PacketEnqueued (Ptr > queue, (queue->GetMode () == QueueBase::QUEUE_MODE_BYTES && queue->GetNBytes () + mtu > queue->GetMaxBytes ())) { - NDQI_LOG (LOG_DEBUG, "The device queue is being stopped (" << queue->GetNPackets () - << " packets and " << queue->GetNBytes () << " bytes inside)"); + NS_LOG_DEBUG ("The device queue is being stopped (" << queue->GetNPackets () + << " packets and " << queue->GetNBytes () << " bytes inside)"); ndqi->GetTxQueue (txq)->Stop (); } } @@ -402,8 +387,9 @@ NetDeviceQueue::PacketDequeued (Ptr > queue, Ptr ndqi, uint8_t txq, Ptr item) { - NDQI_LOG (LOG_LOGIC, "NetDeviceQueue:PacketDequeued(" << queue << ", " << ndqi - << ", " << txq << ", " << item << ")"); + NS_LOG_STATIC_TEMPLATE_DEFINE ("NetDeviceQueueInterface"); + + NS_LOG_FUNCTION (queue << ndqi << txq << item); // Inform BQL ndqi->GetTxQueue (txq)->NotifyTransmittedBytes (item->GetSize ()); @@ -429,16 +415,17 @@ NetDeviceQueue::PacketDiscarded (Ptr > queue, Ptr ndqi, uint8_t txq, Ptr item) { - NDQI_LOG (LOG_LOGIC, "NetDeviceQueue:PacketDiscarded(" << queue << ", " << ndqi - << ", " << txq << ", " << item << ")"); + NS_LOG_STATIC_TEMPLATE_DEFINE ("NetDeviceQueueInterface"); + + NS_LOG_FUNCTION (queue << ndqi << txq << item); // This method is called when a packet is discarded before being enqueued in the // device queue, likely because the queue is full. This should not happen if the // device correctly stops the queue. Anyway, stop the tx queue, so that the upper // layers do not send packets until there is room in the queue again. - NDQI_LOG (LOG_ERROR, "BUG! No room in the device queue for the received packet! (" - << queue->GetNPackets () << " packets and " << queue->GetNBytes () << " bytes inside)"); + NS_LOG_ERROR ("BUG! No room in the device queue for the received packet! (" + << queue->GetNPackets () << " packets and " << queue->GetNBytes () << " bytes inside)"); ndqi->GetTxQueue (txq)->Stop (); } diff --git a/src/network/utils/queue.cc b/src/network/utils/queue.cc index b5d7f226b..e7e64c3a5 100644 --- a/src/network/utils/queue.cc +++ b/src/network/utils/queue.cc @@ -266,10 +266,4 @@ QueueBase::GetMaxBytes (void) const return m_maxBytes; } -void -QueueBase::DoNsLog (const enum LogLevel level, std::string str) const -{ - NS_LOG (level, str); -} - } // namespace ns3 diff --git a/src/network/utils/queue.h b/src/network/utils/queue.h index 5eef2b952..6085f1fa9 100644 --- a/src/network/utils/queue.h +++ b/src/network/utils/queue.h @@ -229,15 +229,6 @@ public: double GetDroppedPacketsPerSecondVariance (void); #endif -protected: - /** - * \brief Actually pass messages to the ns-3 logging system - * - * \param level the log level - * \param str the message to log - */ - void DoNsLog (const enum LogLevel level, std::string str) const; - private: TracedValue m_nBytes; //!< Number of bytes in the queue uint32_t m_nTotalReceivedBytes; //!< Total received bytes @@ -417,6 +408,7 @@ protected: private: std::list > m_packets; //!< the items in the queue + NS_LOG_TEMPLATE_DECLARE; //!< the log component /// Traced callback: fired when a packet is enqueued TracedCallback > m_traceEnqueue; @@ -431,14 +423,6 @@ private: }; -#define QUEUE_LOG(level,params) \ - { \ - std::stringstream ss; \ - ss << params; \ - QueueBase::DoNsLog (level, ss.str ()); \ - } - - /** * Implementation of the templates declared above. */ @@ -472,6 +456,7 @@ Queue::GetTypeId (void) template Queue::Queue () + : NS_LOG_TEMPLATE_DEFINE ("Queue") { } @@ -484,18 +469,18 @@ template bool Queue::DoEnqueue (ConstIterator pos, Ptr item) { - QUEUE_LOG (LOG_LOGIC, "Queue:DoEnqueue(" << this << ", " << item << ")"); + NS_LOG_FUNCTION (this << item); if (m_mode == QUEUE_MODE_PACKETS && (m_nPackets.Get () >= m_maxPackets)) { - QUEUE_LOG (LOG_LOGIC, "Queue full (at max packets) -- dropping pkt"); + NS_LOG_LOGIC ("Queue full (at max packets) -- dropping pkt"); DropBeforeEnqueue (item); return false; } if (m_mode == QUEUE_MODE_BYTES && (m_nBytes.Get () + item->GetSize () > m_maxBytes)) { - QUEUE_LOG (LOG_LOGIC, "Queue full (packet would exceed max bytes) -- dropping pkt"); + NS_LOG_LOGIC ("Queue full (packet would exceed max bytes) -- dropping pkt"); DropBeforeEnqueue (item); return false; } @@ -509,7 +494,7 @@ Queue::DoEnqueue (ConstIterator pos, Ptr item) m_nPackets++; m_nTotalReceivedPackets++; - QUEUE_LOG (LOG_LOGIC, "m_traceEnqueue (p)"); + NS_LOG_LOGIC ("m_traceEnqueue (p)"); m_traceEnqueue (item); return true; @@ -519,11 +504,11 @@ template Ptr Queue::DoDequeue (ConstIterator pos) { - QUEUE_LOG (LOG_LOGIC, "Queue:DoDequeue(" << this << ")"); + NS_LOG_FUNCTION (this); if (m_nPackets.Get () == 0) { - QUEUE_LOG (LOG_LOGIC, "Queue empty"); + NS_LOG_LOGIC ("Queue empty"); return 0; } @@ -538,7 +523,7 @@ Queue::DoDequeue (ConstIterator pos) m_nBytes -= item->GetSize (); m_nPackets--; - QUEUE_LOG (LOG_LOGIC, "m_traceDequeue (p)"); + NS_LOG_LOGIC ("m_traceDequeue (p)"); m_traceDequeue (item); } return item; @@ -548,11 +533,11 @@ template Ptr Queue::DoRemove (ConstIterator pos) { - QUEUE_LOG (LOG_LOGIC, "Queue:DoRemove(" << this << ")"); + NS_LOG_FUNCTION (this); if (m_nPackets.Get () == 0) { - QUEUE_LOG (LOG_LOGIC, "Queue empty"); + NS_LOG_LOGIC ("Queue empty"); return 0; } @@ -576,7 +561,7 @@ template void Queue::Flush (void) { - QUEUE_LOG (LOG_LOGIC, "Queue:Flush(" << this << ")"); + NS_LOG_FUNCTION (this); while (!IsEmpty ()) { Remove (); @@ -587,11 +572,11 @@ template Ptr Queue::DoPeek (ConstIterator pos) const { - QUEUE_LOG (LOG_LOGIC, "Queue:DoPeek(" << this << ")"); + NS_LOG_FUNCTION (this); if (m_nPackets.Get () == 0) { - QUEUE_LOG (LOG_LOGIC, "Queue empty"); + NS_LOG_LOGIC ("Queue empty"); return 0; } @@ -614,14 +599,14 @@ template void Queue::DropBeforeEnqueue (Ptr item) { - QUEUE_LOG (LOG_LOGIC, "Queue:DropBeforeEnqueue(" << this << ", " << item << ")"); + NS_LOG_FUNCTION (this << item); m_nTotalDroppedPackets++; m_nTotalDroppedPacketsBeforeEnqueue++; m_nTotalDroppedBytes += item->GetSize (); m_nTotalDroppedBytesBeforeEnqueue += item->GetSize (); - QUEUE_LOG (LOG_LOGIC, "m_traceDropBeforeEnqueue (p)"); + NS_LOG_LOGIC ("m_traceDropBeforeEnqueue (p)"); m_traceDrop (item); m_traceDropBeforeEnqueue (item); } @@ -630,14 +615,14 @@ template void Queue::DropAfterDequeue (Ptr item) { - QUEUE_LOG (LOG_LOGIC, "Queue:DropAfterDequeue(" << this << ", " << item << ")"); + NS_LOG_FUNCTION (this << item); m_nTotalDroppedPackets++; m_nTotalDroppedPacketsAfterDequeue++; m_nTotalDroppedBytes += item->GetSize (); m_nTotalDroppedBytesAfterDequeue += item->GetSize (); - QUEUE_LOG (LOG_LOGIC, "m_traceDropAfterDequeue (p)"); + NS_LOG_LOGIC ("m_traceDropAfterDequeue (p)"); m_traceDrop (item); m_traceDropAfterDequeue (item); } diff --git a/src/wifi/model/wifi-mac-queue.cc b/src/wifi/model/wifi-mac-queue.cc index 029cc83c8..d0a1a1953 100644 --- a/src/wifi/model/wifi-mac-queue.cc +++ b/src/wifi/model/wifi-mac-queue.cc @@ -111,6 +111,7 @@ WifiMacQueue::GetTypeId (void) template<> WifiMacQueue::WifiQueue () + : NS_LOG_TEMPLATE_DEFINE ("WifiMacQueue") { } diff --git a/src/wifi/model/wifi-mac-queue.h b/src/wifi/model/wifi-mac-queue.h index 09e023c20..3d7c7dd1a 100644 --- a/src/wifi/model/wifi-mac-queue.h +++ b/src/wifi/model/wifi-mac-queue.h @@ -319,6 +319,8 @@ private: Time m_maxDelay; //!< Time to live for packets in the queue DropPolicy m_dropPolicy; //!< Drop behavior of queue + + NS_LOG_TEMPLATE_DECLARE; //!< redefinition of the log component }; /// Forward declare overridden methods to avoid specializing after instantiation