From c384b746f77d69b68fcbf0554bd7e7ef1fe0379a Mon Sep 17 00:00:00 2001 From: Mathieu Lacage Date: Tue, 28 Aug 2007 14:51:13 +0200 Subject: [PATCH] add doxygen documentation and rename TraceContext::Get to TraceContext::GetElement --- src/core/composite-trace-resolver.cc | 2 +- src/core/trace-context.cc | 32 +++++++++---------- src/core/trace-context.h | 46 ++++++++++++++++++++-------- src/core/trace-resolver.h | 15 ++++++--- src/internet-node/pcap-trace.cc | 2 +- 5 files changed, 63 insertions(+), 34 deletions(-) diff --git a/src/core/composite-trace-resolver.cc b/src/core/composite-trace-resolver.cc index 5f04b2c28..fb0c85d01 100644 --- a/src/core/composite-trace-resolver.cc +++ b/src/core/composite-trace-resolver.cc @@ -374,7 +374,7 @@ void CompositeTraceResolverTest::TraceDouble (TraceContext const &context, double v) { TraceSourceTest source; - context.Get (source); + context.GetElement (source); if (source.IsDoubleA ()) { m_gotDoubleA = true; diff --git a/src/core/trace-context.cc b/src/core/trace-context.cc index d065bfa73..e09f461ca 100644 --- a/src/core/trace-context.cc +++ b/src/core/trace-context.cc @@ -358,25 +358,25 @@ TraceContextTest::RunTests (void) { ok = false; } - ctx.Get (v0); + ctx.GetElement (v0); ctx.AddElement (v1); - ctx.Get (v1); - ctx.Get (v0); - ctx.Get (v1); + ctx.GetElement (v1); + ctx.GetElement (v0); + ctx.GetElement (v1); TraceContext copy = ctx; - ctx.Get (v0); - ctx.Get (v1); - copy.Get (v0); - copy.Get (v1); + ctx.GetElement (v0); + ctx.GetElement (v1); + copy.GetElement (v0); + copy.GetElement (v1); copy.AddElement (v2); - copy.Get (v0); - copy.Get (v1); - copy.Get (v2); + copy.GetElement (v0); + copy.GetElement (v1); + copy.GetElement (v2); ctx.AddElement (v3); - ctx.Get (v0); - ctx.Get (v1); - ctx.Get (v3); + ctx.GetElement (v0); + ctx.GetElement (v1); + ctx.GetElement (v3); if (ctx.SafeGet (v2)) { @@ -387,13 +387,13 @@ TraceContextTest::RunTests (void) ok = false; } ctx.Union (copy); - ctx.Get (v2); + ctx.GetElement (v2); if (copy.SafeGet (v3)) { ok = false; } copy.Union (ctx); - copy.Get (v3); + copy.GetElement (v3); return ok; } diff --git a/src/core/trace-context.h b/src/core/trace-context.h index fef2adcc6..13c9f15a7 100644 --- a/src/core/trace-context.h +++ b/src/core/trace-context.h @@ -34,8 +34,10 @@ namespace ns3 { * * Instances of this class are used to hold context * for each trace source. Each instance holds a list of - * 'contexts'. Trace sinks can lookup these contexts + * TraceContextElement. Trace sinks can lookup these contexts * from this list with the ns3::TraceContext::Get method. + * They can also ask the TraceContext for the list of + * TraceContextElements it contains with the PrintAvailable method. * * This class is implemented * using Copy On Write which means that copying unmodified @@ -54,6 +56,9 @@ public: /** * \param context add context to list of trace contexts. + * + * A copy of the input context is appended at the end of the list + * stored in this TraceContext. */ template void AddElement (T const &context); @@ -63,7 +68,7 @@ public: * * Perform the Union operation (in the sense of set theory) on the * two input lists of elements. This method is used in the - * ns3::CallbackTraceSourceSource class when multiple sinks are connected + * ns3::CallbackTraceSource class when multiple sinks are connected * to a single source to ensure that the source does not need * to store a single TraceContext instance per connected sink. * Instead, all sinks share the same TraceContext. @@ -72,15 +77,35 @@ public: /** * \param context context to get from this list of trace contexts. - * - * This method cannot fail. If the requested trace context is not - * stored in this TraceContext, then, the program will halt. + * \returns true if the requested trace context element was found + * in this TraceContext, false otherwise. */ template - void Get (T &context) const; + bool GetElement (T &context) const; + /** + * \param os a c++ STL output stream + * + * Iterate over the list of TraceContextElement stored in this + * TraceContext and invoke each of their Print method. + */ void Print (std::ostream &os) const; + /** + * \param os a c++ STL output stream + * \param separator the separator inserted between each TraceContextElement typename. + * + * Print the typename of each TraceContextElement stored in this TraceContext. + */ void PrintAvailable (std::ostream &os, std::string separator) const; + /** + * \param o another trace context + * \returns true if the input trace context contains exactly the same set of + * TraceContextElement instances, false otherwise. + * + * This method does not test for equality: the content of each matching + * TraceContextElement could be different. It merely checks that both + * trace contexts contain the same types of TraceContextElements. + */ bool IsSimilar (const TraceContext &o) const; private: friend class TraceContextTest; @@ -123,8 +148,8 @@ TraceContext::AddElement (T const &context) } } template -void -TraceContext::Get (T &context) const +bool +TraceContext::GetElement (T &context) const { TraceContextElement *parent; // if the following assignment fails, it is because the input @@ -132,10 +157,7 @@ TraceContext::Get (T &context) const parent = &context; uint8_t *data = (uint8_t *) &context; bool found = DoGet (T::GetUid (), data); - if (!found) - { - NS_FATAL_ERROR ("Type not stored in TraceContext"); - } + return found; } template bool diff --git a/src/core/trace-resolver.h b/src/core/trace-resolver.h index 762717728..dcc0f9699 100644 --- a/src/core/trace-resolver.h +++ b/src/core/trace-resolver.h @@ -35,10 +35,9 @@ class CallbackBase; * namespace resolution. * \ingroup tracing * - * Subclasses must implement the two pure virtal methods defined in - * this base class: - * - ns3::TraceResolver::Connect - * - ns3::TraceResolver::Disconnect. + * Although users could conceivably implement their own trace resolver + * subclasses, doing so is complicated so, it is recommended to use + * the default implementation ns3::CompositeTraceResolver instead. */ class TraceResolver { @@ -88,6 +87,14 @@ public: typedef std::vector SourceVector; SourceVector m_sources; }; + /** + * \param path the path to the current recursive level. + * \param context the trace context associated to the current recursive level + * \param collection the collection in which to gather every trace source found. + * + * This method is invoked recursively until all trace sources have been + * stored in the output SourceCollection argument. + */ virtual void CollectSources (std::string path, const TraceContext &context, SourceCollection *collection) = 0; protected: diff --git a/src/internet-node/pcap-trace.cc b/src/internet-node/pcap-trace.cc index dd0b39a29..3378b52c5 100644 --- a/src/internet-node/pcap-trace.cc +++ b/src/internet-node/pcap-trace.cc @@ -83,7 +83,7 @@ void PcapTrace::LogIp (TraceContext const &context, Packet const &p, uint32_t interfaceIndex) { NodeListIndex nodeIndex; - context.Get (nodeIndex); + context.GetElement (nodeIndex); PcapWriter *writer = GetStream (nodeIndex.Get (), interfaceIndex); writer->WritePacket (p); }