diff --git a/.hgtags b/.hgtags index 59f333e81..4d11c256c 100644 --- a/.hgtags +++ b/.hgtags @@ -12,3 +12,4 @@ b5bf2588cde2f1273b1095cc5c83a0c272e55370 release ns-3.0.10 ee5e1da76ecc52337f097cd90ebb50a3d49ec541 release-3.0.11 b17f2928291eec5bf5b1c59a4a5fd583f704ac40 release ns-3.0.12 +79dba133b5f8a2d6f6f678a22e8519bc155e6a4e release ns-3.0.13 diff --git a/RELEASE_NOTES b/RELEASE_NOTES index 2afcd900d..572bc13d7 100644 --- a/RELEASE_NOTES +++ b/RELEASE_NOTES @@ -3,6 +3,26 @@ This file contains ns-3 release notes (most recent releases first). +Release 3.0.13 (2008/06/02) +======================== +- point to point links generate ppp pcap traces +- point to point links support asymmetrical data rates. +- generate doxygen documentation for all attributes and trace sources +- add ConfigStore and GtkConfigStore to contrib module +- socket API now support tx and rx buffers: implemented for UDP and TCP +- ARP cache now supports per-entry pending queues +- lots of bugfixes and implementation and API cleanups + +Warning: among API changes in this release, Application::Start and +Application::Stop now interprets the time argument as a relative +instead of absolute simulation time, to align with how Simulator::Schedule +behaves. Any code that calls these APIs in the middle of the simulation +will need to be adapted. + +The API of Simulator::StopAt (time) has also changed. Now it is +called Simulator::Stop (time), and takes a relative time, instead of +absolute. + Release 3.0.12 (2008/04/07) ======================== - Add Attribute support to the TypeId metadata system and add diff --git a/VERSION b/VERSION index f93fc9f42..eea30e595 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -3.0.12 +3.0.13 diff --git a/doc/modules b/doc/modules index afc272c94..d16f351fb 100644 --- a/doc/modules +++ b/doc/modules @@ -13,7 +13,7 @@ * - a Functor class: ns3::Callback * - an os-independent interface to get access to the elapsed wall clock time: ns3::SystemWallClockMs * - a class to register regression tests with the test manager: ns3::Test and ns3::TestManager - * - debugging facilities: \ref logging, \ref assert, \ref error + * - debugging facilities: \ref logging, \ref assert * - \ref randomvariable * - a base class for objects which need to support per-instance "attributes" and * trace sources: ns3::ObjectBase diff --git a/doc/release_steps.txt b/doc/release_steps.txt index aef31952a..a31da0fba 100644 --- a/doc/release_steps.txt +++ b/doc/release_steps.txt @@ -6,7 +6,7 @@ Steps in doing an ns-3 release - revise and check in RELEASE_NOTES - update and check in VERSION to the latest release number - confirm that Doxygen builds cleanly and without warnings - (./waf --doxygen), and check in any necessary changes + (./waf check; ./waf --doxygen), and check in any necessary changes 2. ./waf configure; ./waf dist - this will create a ns-3.0.x.tar.bz2 tarball - this will also create a ns-3.0.x-ref-traces.tar.bz2 tarball @@ -23,7 +23,7 @@ Steps in doing an ns-3 release 6. Run the regression tests on the new release and update the reference traces - ./waf --regression - ./waf --valgrind --regression (for valgrind version) - - There should be no regressions at this time + - There should be no regression errors at this time - tag ns-3-dev-ref-traces with "release ns-3.0.X" hg tag "release ns-3.0.x" hg push diff --git a/src/common/data-writer.cc b/src/common/data-writer.cc deleted file mode 100644 index fc4d0b13f..000000000 --- a/src/common/data-writer.cc +++ /dev/null @@ -1,120 +0,0 @@ -/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ -/* - * Copyright (c) 2005 INRIA - * - * 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: Mathieu Lacage - */ -#include "data-writer.h" - -#include -#include -#include -#include -#include -#include "ns3/assert.h" -#include -#include - -#define noTRACE_DATA_WRITER 1 - -#ifdef TRACE_DATA_WRITER -#include -# define TRACE(x) \ -std::cout << "DATA WRITER TRACE " << this << " " << x << std::endl; -#else /* TRACE_DATA_WRITER */ -# define TRACE(format,...) -#endif /* TRACE_DATA_WRITER */ - -#define BUFFER_SIZE (4096) - - -namespace ns3 { - -class DataWriterPrivate { -public: - DataWriterPrivate (); - ~DataWriterPrivate (); - - void open (char const *filename); - void write (uint8_t *buffer, uint32_t size); -private: - uint8_t m_data[BUFFER_SIZE]; - uint32_t m_current; - int m_fd; -}; - -DataWriterPrivate::DataWriterPrivate () - : m_current (0) -{} -DataWriterPrivate::~DataWriterPrivate () -{ - ::Write (m_fd, m_data, m_current); - ::Close (m_fd); -} - - -void -DataWriterPrivate::Open (char const *filename) -{ - m_fd = ::Open (filename, O_WRONLY | O_CREAT | O_TRUNC, S_IRUSR | S_IWUSR); - NS_ASSERT (m_fd != -1); -} - -#ifndef min -#define min(a,b) ((a)<(b)?(a):(b)) -#endif /* min */ - -void -DataWriterPrivate::Write (uint8_t *buffer, uint32_t size) -{ - while (size > 0) - { - uint32_t toCopy = min (BUFFER_SIZE - m_current, size); - memcpy (m_data + m_current, buffer, toCopy); - size -= toCopy; - m_current += toCopy; - buffer += toCopy; - if (m_current == BUFFER_SIZE) - { - ssize_t written = 0; - written = ::Write (m_fd, m_data, BUFFER_SIZE); - NS_ASSERT (written == BUFFER_SIZE); - m_current = 0; - } - } -} - -DataWriter::DataWriter () - : m_priv (new DataWriterPrivate ()) -{} -DataWriter::~DataWriter () -{ - delete m_priv; - m_priv = 0; -} - -void -DataWriter::Open (char const *filename) -{ - m_priv->Open (filename); -} -void -DataWriter::Write (uint8_t *buffer, uint32_t size) -{ - m_priv->Write (buffer, size); -} - -}; // namespace diff --git a/src/common/data-writer.h b/src/common/data-writer.h deleted file mode 100644 index 28496c489..000000000 --- a/src/common/data-writer.h +++ /dev/null @@ -1,43 +0,0 @@ -/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ -/* - * Copyright (c) 2005 INRIA - * - * 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: Mathieu Lacage - */ - -#ifndef DATA_WRITER_H -#define DATA_WRITER_H - -#include - -namespace ns3 { - -class DataWriterPrivate; - -class DataWriter { -public: - DataWriter (); - ~DataWriter (); - - void open (char const *filename); - void write (uint8_t *buffer, uint32_t size); -private: - DataWriterPrivate *m_priv; -}; - -}; //namespace ns3 - -#endif /* DATA_WRITER_H */ diff --git a/src/common/header.h b/src/common/header.h index 8ad22c7e5..7a7dd4529 100644 --- a/src/common/header.h +++ b/src/common/header.h @@ -34,9 +34,7 @@ namespace ns3 { * * Every Protocol header which needs to be inserted or removed * from a Packet instance must derive from this base class and - * implement the following public methods: - * - a default constructor: is used by the internal implementation - * if the Packet class. + * implement the pure virtual methods defined here. * * Sample code which shows how to create a new type of Header, and how to use it, * is shown in the sample file samples/main-packet-header.cc diff --git a/src/common/packet.h b/src/common/packet.h index 2e5d9ef49..5c5969efe 100644 --- a/src/common/packet.h +++ b/src/common/packet.h @@ -42,7 +42,7 @@ class TagIterator { public: /** - * Identifies a set tag and a set of bytes within a packet + * Identifies a tag and a set of bytes within a packet * to which the tag applies. */ class Item diff --git a/src/common/pcap-writer.h b/src/common/pcap-writer.h index 52450a117..10a6528d7 100644 --- a/src/common/pcap-writer.h +++ b/src/common/pcap-writer.h @@ -51,17 +51,35 @@ public: /** * Write a pcap header in the output file which specifies - * that the content of the file will Packets with + * that the content of the file will be Packets with * Ethernet/LLC/SNAP encapsulation. This method should * be invoked before ns3::PcapWriter::writePacket and after * ns3::PcapWriter::open. */ void WriteEthernetHeader (void); + /** + * Write a pcap header in the output file which specifies + * that the content of the file will be IPv4 Packets. This + * method should be invoked before ns3::PcapWriter::WritePacket + * and after ns3::PcapWriter::Open. + */ void WriteIpHeader (void); + /** + * Write a pcap header in the output file which specifies + * that the content of the file will be 802.11 Packets. This + * method should be invoked before ns3::PcapWriter::WritePacket + * and after ns3::PcapWriter::Open. + */ void WriteWifiHeader (void); + /** + * Write a pcap header in the output file which specifies + * that the content of the file will be ppp Packets. This + * method should be invoked before ns3::PcapWriter::WritePacket + * and after ns3::PcapWriter::Open. + */ void WritePppHeader (void); /** diff --git a/src/common/tag-buffer.h b/src/common/tag-buffer.h index 6ef0e94cd..43a488caa 100644 --- a/src/common/tag-buffer.h +++ b/src/common/tag-buffer.h @@ -38,28 +38,106 @@ namespace ns3 { * \brief read and write tag data * * This class allows subclasses of the ns3::Tag base class - * to serialize and deserialize their data. + * to serialize and deserialize their data through a stream-like + * API. This class keeps track of the "current" point in the + * buffer and advances that "current" point everytime data is + * written. The in-memory format of the data written by + * this class is unspecified. + * + * If the user attempts to write more data in the buffer than + * he allocated with Tag::GetSerializedSize, he will trigger + * an NS_ASSERT error. */ class TagBuffer { public: TagBuffer (uint8_t *start, uint8_t *end); void TrimAtEnd (uint32_t trim); - - TAG_BUFFER_INLINE void WriteU8 (uint8_t v); - TAG_BUFFER_INLINE void WriteU16 (uint16_t v); - TAG_BUFFER_INLINE void WriteU32 (uint32_t v); - void WriteU64 (uint64_t v); - void WriteDouble (double v); - void Write (const uint8_t *buffer, uint32_t size); - TAG_BUFFER_INLINE uint8_t ReadU8 (void); - TAG_BUFFER_INLINE uint16_t ReadU16 (void); - TAG_BUFFER_INLINE uint32_t ReadU32 (void); - uint64_t ReadU64 (void); - double ReadDouble (void); - void Read (uint8_t *buffer, uint32_t size); - void CopyFrom (TagBuffer o); + + /** + * \param v the value to write + * + * Write one byte and advance the "current" point by one. + */ + TAG_BUFFER_INLINE void WriteU8 (uint8_t v); + /** + * \param v the value to write + * + * Write two bytes and advance the "current" point by two. + */ + TAG_BUFFER_INLINE void WriteU16 (uint16_t v); + /** + * \param v the value to write + * + * Write four bytes and advance the "current" point by four. + */ + TAG_BUFFER_INLINE void WriteU32 (uint32_t v); + /** + * \param v the value to write + * + * Write eight bytes and advance the "current" point by eight. + */ + void WriteU64 (uint64_t v); + /** + * \param v the value to write + * + * Write a double and advance the "current" point by the size of the + * data written. + */ + void WriteDouble (double v); + /** + * \param buffer a pointer to data to write + * \param size the size of the data to write + * + * Write all the input data and advance the "current" point by the size of the + * data written. + */ + void Write (const uint8_t *buffer, uint32_t size); + /** + * \returns the value read + * + * Read one byte, advance the "current" point by one, + * and return the value read. + */ + TAG_BUFFER_INLINE uint8_t ReadU8 (void); + /** + * \returns the value read + * + * Read two bytes, advance the "current" point by two, + * and return the value read. + */ + TAG_BUFFER_INLINE uint16_t ReadU16 (void); + /** + * \returns the value read + * + * Read four bytes, advance the "current" point by four, + * and return the value read. + */ + TAG_BUFFER_INLINE uint32_t ReadU32 (void); + /** + * \returns the value read + * + * Read eight bytes, advance the "current" point by eight, + * and return the value read. + */ + uint64_t ReadU64 (void); + /** + * \returns the value read + * + * Read a double, advance the "current" point by the size + * of the data read, and, return the value read. + */ + double ReadDouble (void); + /** + * \param buffer a pointer to the buffer where data should be + * written. + * \param size the number of bytes to read. + * + * Read the number of bytes requested, advance the "current" + * point by the number of bytes read, return. + */ + void Read (uint8_t *buffer, uint32_t size); private: uint8_t *m_current; diff --git a/src/common/tag.h b/src/common/tag.h index 8454ae394..ed8240296 100644 --- a/src/common/tag.h +++ b/src/common/tag.h @@ -49,12 +49,16 @@ public: * \param i the buffer to write data into. * * Write the content of the tag in the provided tag buffer. + * DO NOT attempt to write more bytes than you requested + * with Tag::GetSerializedSize. */ virtual void Serialize (TagBuffer i) const = 0; /** * \param i the buffer to read data from. * * Read the content of the tag from the provided tag buffer. + * DO NOT attempt to read more bytes than you wrote with + * Tag::Serialize. */ virtual void Deserialize (TagBuffer i) = 0; }; diff --git a/src/common/trailer.h b/src/common/trailer.h index 70eb25130..c3840021b 100644 --- a/src/common/trailer.h +++ b/src/common/trailer.h @@ -35,9 +35,7 @@ namespace ns3 { * * Every Protocol trailer which needs to be inserted or removed * from a Packet instance must derive from this base class and - * implement the following public methods: - * - a default constructor: is used by the internal implementation - * if the Packet class. + * implement the pure virtual methods defined here. */ class Trailer : public Chunk { diff --git a/src/core/attribute-list.cc b/src/core/attribute-list.cc index 2ec595d3a..8d92ad16b 100644 --- a/src/core/attribute-list.cc +++ b/src/core/attribute-list.cc @@ -212,7 +212,7 @@ AttributeList::DeserializeFromString (std::string str) std::string::size_type equal = str.find ("=", cur); if (equal == std::string::npos) { - // XXX: invalid attribute. + NS_FATAL_ERROR ("Error while parsing serialized attribute: \"" << str << "\""); break; } else @@ -221,7 +221,7 @@ AttributeList::DeserializeFromString (std::string str) struct TypeId::AttributeInfo info; if (!TypeId::LookupAttributeByFullName (name, &info)) { - // XXX invalid name. + NS_FATAL_ERROR ("Error while parsing serialized attribute: name does not exist: \"" << name << "\""); break; } else @@ -242,7 +242,7 @@ AttributeList::DeserializeFromString (std::string str) bool ok = val->DeserializeFromString (value, info.checker); if (!ok) { - // XXX invalid value + NS_FATAL_ERROR ("Error while parsing serialized attribute: value invalid: \"" << value << "\""); break; } else diff --git a/src/core/attribute-list.h b/src/core/attribute-list.h index 36bda6735..be2583f43 100644 --- a/src/core/attribute-list.h +++ b/src/core/attribute-list.h @@ -87,7 +87,6 @@ public: */ static AttributeList *GetGlobal (void); - // XXX: untested. std::string SerializeToString (void) const; bool DeserializeFromString (std::string value); private: diff --git a/src/core/attribute-test.cc b/src/core/attribute-test.cc index 64eee0837..594051895 100644 --- a/src/core/attribute-test.cc +++ b/src/core/attribute-test.cc @@ -167,7 +167,7 @@ public: MakeTraceSourceAccessor (&AttributeObjectTest::m_cb)) .AddTraceSource ("ValueSource", "help text", MakeTraceSourceAccessor (&AttributeObjectTest::m_valueSrc)) - .AddAttribute ("Pointer", "XXX", + .AddAttribute ("Pointer", "help text", PointerValue (), MakePointerAccessor (&AttributeObjectTest::m_ptr), MakePointerChecker ()) diff --git a/src/core/attribute.h b/src/core/attribute.h index aa16c8634..a18f3694a 100644 --- a/src/core/attribute.h +++ b/src/core/attribute.h @@ -144,7 +144,7 @@ public: * to detect the type of the associated attribute. * * Most subclasses of this base class are implemented by the - * ATTRIBUTE_HELPER_* macros. + * \ref ATTRIBUTE_HELPER_HEADER and \ref ATTRIBUTE_HELPER_CPP macros. */ class AttributeChecker : public RefCountBase { diff --git a/src/core/command-line.h b/src/core/command-line.h index 2a5948361..a03cff92b 100644 --- a/src/core/command-line.h +++ b/src/core/command-line.h @@ -28,6 +28,7 @@ namespace ns3 { /** * \brief parse command-line arguments + * \ingroup core * * Instances of this class can be used to parse command-line * arguments: users can register new arguments with diff --git a/src/core/config.h b/src/core/config.h index 6346b071b..256b491ef 100644 --- a/src/core/config.h +++ b/src/core/config.h @@ -29,6 +29,10 @@ class AttributeValue; class Object; class CallbackBase; +/** + * \brief Configuration of simulation parameters and tracing + * \ingroup core + */ namespace Config { /** diff --git a/src/core/object-vector.cc b/src/core/object-vector.cc index bca66f8af..663b34dc4 100644 --- a/src/core/object-vector.cc +++ b/src/core/object-vector.cc @@ -34,8 +34,16 @@ ObjectVectorValue::Copy (void) const std::string ObjectVectorValue::SerializeToString (Ptr checker) const { - // XXX - return ""; + std::ostringstream oss; + for (uint32_t i = 0; i < m_objects.size (); ++i) + { + oss << m_objects[i]; + if (i != m_objects.size () - 1) + { + oss << " "; + } + } + return oss.str (); } bool ObjectVectorValue::DeserializeFromString (std::string value, Ptr checker) diff --git a/src/core/object.h b/src/core/object.h index c136e89ae..dcaf97e36 100644 --- a/src/core/object.h +++ b/src/core/object.h @@ -46,6 +46,14 @@ class TraceSourceAccessor; * \ingroup object * \brief a base class which provides memory management and object aggregation * + * The memory management scheme is based on reference-counting with dispose-like + * functionality to break the reference cycles. The reference count is increamented + * and decremented with the methods Object::Ref and Object::Unref. If a reference cycle is + * present, the user is responsible for breaking it by calling Object::Dispose in + * a single location. This will eventually trigger the invocation of Object::DoDispose + * on itself and all its aggregates. The Object::DoDispose method is always automatically + * invoked from the Object::Unref method before destroying the object, even if the user + * did not call Object::Dispose directly. */ class Object : public ObjectBase { diff --git a/src/core/singleton.h b/src/core/singleton.h index 722d93a62..77f51d58d 100644 --- a/src/core/singleton.h +++ b/src/core/singleton.h @@ -22,6 +22,17 @@ namespace ns3 { +/** + * \brief a template singleton + * + * This template class can be used to implement the singleton pattern. + * The underlying object will be destroyed automatically when the process + * exits. Note that, if you call Singleton::Get again after the object has + * been destroyed, the object will be re-created which will result in a + * memory leak as reported by most memory leak checkers. It is up to the + * user to ensure that Singleton::Get is never called from a static variable + * finalizer. + */ template class Singleton { diff --git a/src/core/trace-source-accessor.h b/src/core/trace-source-accessor.h index 4a76aa598..e85f260ca 100644 --- a/src/core/trace-source-accessor.h +++ b/src/core/trace-source-accessor.h @@ -74,7 +74,10 @@ private: * \param a the trace source * * Create a TraceSourceAccessor which will control access to the underlying - * trace source. + * trace source. This helper template method assumes that the underlying + * type implements a statically-polymorphic set of Connect and Disconnect + * methods and creates a dynamic-polymorphic class to wrap the underlying + * static-polymorphic class. */ template Ptr MakeTraceSourceAccessor (T a); diff --git a/src/core/traced-value.h b/src/core/traced-value.h index 837c0536a..79abdd10c 100644 --- a/src/core/traced-value.h +++ b/src/core/traced-value.h @@ -47,7 +47,7 @@ namespace ns3 { * this template: this instance will behave just like * the original class (if it did not export any special method), * and will define Connect/DisconnectWithoutContext methods to work - * with an ns3::TraceSourceAccessor. + * with ns3::MakeTraceSourceAccessor. */ template class TracedValue diff --git a/src/devices/wifi/nqap-wifi-mac.cc b/src/devices/wifi/nqap-wifi-mac.cc index e156d2f3b..db8add000 100644 --- a/src/devices/wifi/nqap-wifi-mac.cc +++ b/src/devices/wifi/nqap-wifi-mac.cc @@ -44,7 +44,7 @@ NqapWifiMac::GetTypeId (void) .SetParent () .AddConstructor () .AddAttribute ("BeaconInterval", "Delay between two beacons", - TimeValue (Seconds (1.0)), + TimeValue (Seconds (0.1)), MakeTimeAccessor (&NqapWifiMac::m_beaconInterval), MakeTimeChecker ()) .AddAttribute ("BeaconGeneration", "Whether or not beacons are generated.", diff --git a/src/node/application.h b/src/node/application.h index 2834847da..f34a1e5e4 100644 --- a/src/node/application.h +++ b/src/node/application.h @@ -34,7 +34,7 @@ class RandomVariable; /** * \ingroup node - * \defgroup application + * \defgroup application Application * * \brief The base class for all ns3 applicationes *