# HG changeset patch # User Peter D. Barnes, Jr. # Date 1418159869 28800 # Node ID caafe12b0378ced62e3d1cad4f7374a1757ba90e # Parent e57bfdb4f12c4a88dbb2e74b3a09465d0da3de5a [Doxygen] OS functions: filesystem, threading, wall clock. diff -r e57bfdb4f12c -r caafe12b0378 src/core/model/attribute-helper.h --- a/src/core/model/attribute-helper.h Sun Dec 07 22:08:04 2014 -0800 +++ b/src/core/model/attribute-helper.h Tue Dec 09 13:17:49 2014 -0800 @@ -158,7 +158,7 @@ /** * \ingroup attributehelper * - * Declare the attribute value class \p Value + * Declare the attribute value class \p \Value * for underlying class \p type. * * \param type The underlying type name @@ -198,7 +198,7 @@ /** * \ingroup attributehelper * - * Declare the attribute value class \p Value + * Declare the attribute value class \p \Value * for the class \p Name * * \param Name the name of the class. @@ -230,15 +230,15 @@ /** * \ingroup attributehelper * - * Declare the AttributeChecker class \p Checker + * Declare the AttributeChecker class \p \Checker * and the \c MakeTypeChecker function for class \p type. * * \param type the name of the class * - * This macro declares the \p Checker class and the associated + * This macro declares the \p \Checker class and the associated * \c MakeTypeChecker function. * - * (Note that the \p Checker class needs no implementation + * (Note that the \p \Checker class needs no implementation * since it just inherits all its implementation from AttributeChecker.) * * Typically invoked in the class header file. @@ -252,15 +252,15 @@ * \ingroup attributehelper * * Define the class methods belonging to - * the attribute value class \p Value + * the attribute value class \p \Value * of the underlying class \p type. * * \param type The underlying type name * \param name The token to use in defining the accessor name. * - * This macro implements the \p Value class methods - * (including the \p Value::SerializeToString - * and \p Value::DeserializeFromString methods). + * This macro implements the \p \Value class methods + * (including the \p \Value::SerializeToString + * and \p \Value::DeserializeFromString methods). * * Typically invoked in the source file. */ @@ -297,13 +297,13 @@ * \ingroup attributehelper * * Define the class methods belonging to - * attribute value class \p Value for class \p type. + * attribute value class \p \Value for class \p type. * * \param type the name of the class. * - * This macro implements the \p Value class methods - * (including the \p Value::SerializeToString - * and \p Value::DeserializeFromString methods). + * This macro implements the \p \Value class methods + * (including the \p \Value::SerializeToString + * and \p \Value::DeserializeFromString methods). * * Typically invoked in the source file. */ @@ -356,11 +356,11 @@ * * This macro declares: * - * - The attribute value class \p Value, + * - The attribute value class \p \Value, * * - The attribute accessor functions \c MakeTypeAccessor, * - * - The AttributeChecker class \p Checker + * - The AttributeChecker class \p \Checker * and the \c MakeTypeChecker function, * * for class \p type. @@ -382,7 +382,7 @@ * * This macro implements * - * - The \p Value class methods, + * - The \p \Value class methods, * * - The \c MakeTypeChecker function, * diff -r e57bfdb4f12c -r caafe12b0378 src/core/model/system-condition.h --- a/src/core/model/system-condition.h Sun Dec 07 22:08:04 2014 -0800 +++ b/src/core/model/system-condition.h Tue Dec 09 13:17:49 2014 -0800 @@ -21,11 +21,25 @@ #include "ptr.h" -namespace ns3 { +/** + * @file + * @ingroup thread + * System-independent thread conditional wait. + */ + +namespace ns3 { + +/** + * @ingroup system + * @defgroup thread Threading and Signaling. + * + * System-independent interfaces to threads, signal conditions, and mutex. + */ class SystemConditionPrivate; /** + * @ingroup thread * @brief A class which provides a relatively platform-independent * conditional-wait thread synchronization primitive. * @@ -61,7 +75,7 @@ /** * Set the value of the underlying condition. - * \param condition value + * @param condition value */ void SetCondition (bool condition); @@ -92,12 +106,14 @@ /** * Wait a maximum of ns nanoseconds for the condition to be true. If the * wait times out, return true else return false. - * \param ns maximum of nanoseconds to wait + * @param ns maximum of nanoseconds to wait + * @returns true if the timer expired, otherwise return false. */ bool TimedWait (uint64_t ns); private: + /** The (system-dependent) implementation. */ SystemConditionPrivate * m_priv; }; diff -r e57bfdb4f12c -r caafe12b0378 src/core/model/system-mutex.h --- a/src/core/model/system-mutex.h Sun Dec 07 22:08:04 2014 -0800 +++ b/src/core/model/system-mutex.h Tue Dec 09 13:17:49 2014 -0800 @@ -23,11 +23,19 @@ #include "ptr.h" +/** + * @file + * @ingroup thread + * System-independent mutex primitive, ns3::SystemMutex, + * and ns3::CriticalSection. + */ + namespace ns3 { class SystemMutexPrivate; /** + * @ingroup thread * @brief A class which provides a relatively platform-independent Mutual * Exclusion thread synchronization primitive. * @@ -64,6 +72,7 @@ void Unlock (); private: + /** The (system-dependent) implementation. */ SystemMutexPrivate * m_priv; }; @@ -73,32 +82,32 @@ * When more than one SystemThread needs to access a shared resource, we * control access by acquiring a SystemMutex. The CriticalSection class uses * the C++ scoping rules to automatically perform the required Lock and Unlock - * operations to implement a Critical Section. + * operations on the shared SystemMutex to implement a Critical Section. * * If one wants to treat an entire method call as a critical section, one would * do something like, - * - * Class::Method () - * { - * CriticalSection cs (mutex); - * ... - * } - * + * @code + * Class::Method () + * { + * CriticalSection cs (mutex); + * ... + * } + * @endcode * In this case, the critical section is entered when the CriticalSection * object is created, and the critical section is exited when the * CriticalSection object goes out of scope at the end of the method. * * Finer granularity is achieved by using local scope blocks. - * - * Class::Method () - * { - * ... + * @code + * Class::Method () * { - * CriticalSection cs (mutex); + * ... + * { + * CriticalSection cs (mutex); + * } + * ... * } - * ... - * } - * + * @endcode * Here, the critical section is entered partway through the method when the * CriticalSection object is created in the local scope block (the braces). * The critical section is exited when the CriticalSection object goes out of @@ -109,10 +118,16 @@ class CriticalSection { public: + /** + * Construct with the required SystemMutex. + * + * @param [in] mutex The mutex. + */ CriticalSection (SystemMutex &mutex); + /** Destructor */ ~CriticalSection (); private: - SystemMutex &m_mutex; + SystemMutex &m_mutex; /**< The mutex. */ }; } // namespace ns3 diff -r e57bfdb4f12c -r caafe12b0378 src/core/model/system-path.cc --- a/src/core/model/system-path.cc Sun Dec 07 22:08:04 2014 -0800 +++ b/src/core/model/system-path.cc Tue Dec 09 13:17:49 2014 -0800 @@ -25,12 +25,16 @@ #include #include #include + + #if defined (HAVE_DIRENT_H) and defined (HAVE_SYS_TYPES_H) +/** Do we have an \c opendir function? */ #define HAVE_OPENDIR #include #include #endif #if defined (HAVE_SYS_STAT_H) and defined (HAVE_SYS_TYPES_H) +/** Do we have a \c makedir function? */ #define HAVE_MKDIR_H #include #include @@ -49,12 +53,22 @@ #include #endif +/** + * \def SYSTEM_PATH_SEP + * System-specific path separator used between directory names. + */ #if defined (__win32__) #define SYSTEM_PATH_SEP "\\" #else #define SYSTEM_PATH_SEP "/" #endif +/** + * \file + * \ingroup systempath + * System-independent file and directory function definitions. + */ + namespace ns3 { NS_LOG_COMPONENT_DEFINE ("SystemPath"); @@ -313,6 +327,8 @@ MakeDirectories (std::string path) { NS_LOG_FUNCTION (path); + + // Make sure all directories on the path exist std::list elements = Split (path); for (std::list::const_iterator i = elements.begin (); i != elements.end (); ++i) { @@ -324,11 +340,13 @@ } #endif } + + // Make the final directory. Is this redundant with last iteration above? #if defined(HAVE_MKDIR_H) - if (mkdir (path.c_str (), S_IRWXU)) - { - NS_LOG_ERROR ("failed creating directory " << path); - } + if (mkdir (path.c_str (), S_IRWXU)) + { + NS_LOG_ERROR ("failed creating directory " << path); + } #endif } diff -r e57bfdb4f12c -r caafe12b0378 src/core/model/system-path.h --- a/src/core/model/system-path.h Sun Dec 07 22:08:04 2014 -0800 +++ b/src/core/model/system-path.h Tue Dec 09 13:17:49 2014 -0800 @@ -23,10 +23,16 @@ #include #include +/** + * \file + * \ingroup systempath + * System-independent file and directory function declarations. + */ + namespace ns3 { /** - * \ingroup testing + * \ingroup system * \defgroup systempath Host Filesystem * \brief Encapsulate OS-specific functions to manipulate file * and directory paths. @@ -36,11 +42,6 @@ */ /** - * \addtogroup core - * \see systempath - */ - -/** * \ingroup systempath * \brief Namespace for various file and directory path functions. */ @@ -48,12 +49,16 @@ /** * \ingroup systempath + * Get the file system path to the current executable. + * * \return the directory in which the currently-executing binary is located */ std::string FindSelfDirectory (void); /** * \ingroup systempath + * Join two file system path elements. + * * \param left a path element * \param right a path element * \return a concatenation of the two input paths @@ -62,6 +67,11 @@ /** * \ingroup systempath + * Split a file system path into directories according to + * the local path separator. + * + * This is the inverse of Join. + * * \param path a path * \return a list of path elements that can be joined together again with * the Join function. @@ -70,6 +80,11 @@ std::list Split (std::string path); /** + * Join a list of file system path directories into a single + * file system path. + * + * This is the inverse of Split. + * * \ingroup systempath * \param begin iterator to first element to join * \param end iterator to last element to join @@ -80,6 +95,8 @@ /** * \ingroup systempath + * Get the list of files located in a file system directory. + * * \param path a path which identifies a directory * \return a list of the filenames which are located in the input directory */ @@ -87,19 +104,21 @@ /** * \ingroup systempath - * \return a path which identifies a temporary directory. + * Get the name of a temporary directory. * - * The returned path identifies a directory which does not exist yet + * The returned path identifies a directory which does not exist yet. * Call ns3::SystemPath::MakeDirectories to create it. Yes, there is a * well-known security race in this API but we don't care in ns-3. + * + * \return a path which identifies a temporary directory. */ std::string MakeTemporaryDirectoryName (void); /** * \ingroup systempath - * \param path a path to a directory + * Create all the directories leading to path. * - * Create all the directories leading to path. + * \param path a path to a directory */ void MakeDirectories (std::string path); diff -r e57bfdb4f12c -r caafe12b0378 src/core/model/system-thread.cc --- a/src/core/model/system-thread.cc Sun Dec 07 22:08:04 2014 -0800 +++ b/src/core/model/system-thread.cc Tue Dec 09 13:17:49 2014 -0800 @@ -23,6 +23,12 @@ #include "log.h" #include +/** + * @file + * @ingroup thread + * System-independent thread class ns3::SystemThread definitions. + */ + namespace ns3 { NS_LOG_COMPONENT_DEFINE ("SystemThread"); diff -r e57bfdb4f12c -r caafe12b0378 src/core/model/system-thread.h --- a/src/core/model/system-thread.h Sun Dec 07 22:08:04 2014 -0800 +++ b/src/core/model/system-thread.h Tue Dec 09 13:17:49 2014 -0800 @@ -27,9 +27,16 @@ #include #endif /* HAVE_PTHREAD_H */ +/** + * @file + * @ingroup thread + * System-independent thread class ns3::SystemThread declaration. + */ + namespace ns3 { /** + * @ingroup thread * @brief A class which provides a relatively platform-independent thread * primitive. * @@ -43,12 +50,15 @@ * execution. * * Synchronization between threads is provided via the SystemMutex class. + * + * See @ref main-test-sync.cc for example usage. */ class SystemThread : public SimpleRefCount { public: #ifdef HAVE_PTHREAD_H + /** Type alias for the system-dependent thread object. */ typedef pthread_t ThreadId; #endif @@ -67,36 +77,39 @@ * * The most common use is expected to be creating a thread of execution in * a method. In this case you would use code similar to, - * + * @code * MyClass myObject; * Ptr st = Create ( * MakeCallback (&MyClass::MyMethod, &myObject)); * st->Start (); + * @endcode * * The SystemThread is passed a callback that calls out to the function - * MyClass::MyMethod. When this function is called, it is called as an - * object method on the myObject object. Essentially what you are doing - * is asking the SystemThread to call object->MyMethod () in a new thread + * @c MyClass::MyMethod. When this function is called, it is called as an + * object method on the @c myObject object. Essentially what you are doing + * is asking the SystemThread to call @c object->MyMethod() in a new thread * of execution. * * If starting a thread in your currently executing object, you can use the * "this" pointer: - * + * @code * Ptr st = Create ( * MakeCallback (&MyClass::MyMethod, this)); * st->Start (); + * @endcode * * Object lifetime is always an issue with threads, so it is common to use * smart pointers. If you are spinning up a thread in an object that is * managed by a smart pointer, you can use that pointer directly: - * + * @code * Ptr myPtr = Create (); * Ptr st = Create ( * MakeCallback (&MyClass::MyMethod, myPtr)); * st->Start (); + * @endcode * * Just like any thread, you can synchronize with its termination. The - * method provided to do this is Join (). If you call Join() you will block + * method provided to do this is Join(). If you call Join() you will block * until the SystemThread run method returns. * * @param callback entry point of the thread @@ -136,18 +149,25 @@ static ThreadId Self(void); /** - * @brief Compares an TharedId with the current ThreadId . + * @brief Compares an ThreadId with the current ThreadId . * - * @returns true if Id matches the current ThreadId. + * @param [in] id The ThreadId to compare to. + * @returns true if @c id matches the current ThreadId. */ static bool Equals(ThreadId id); private: #ifdef HAVE_PTHREAD_H + /** + * Invoke the callback in the new thread. + * + * @param [in] arg This SystemThread instance to communicate to the newly + * launched thread. + */ static void *DoRun (void *arg); - Callback m_callback; - pthread_t m_thread; + Callback m_callback; /**< The main function for this thread when launched. */ + pthread_t m_thread; /**< The thread id of the child thread. */ #endif }; diff -r e57bfdb4f12c -r caafe12b0378 src/core/model/system-wall-clock-ms.h --- a/src/core/model/system-wall-clock-ms.h Sun Dec 07 22:08:04 2014 -0800 +++ b/src/core/model/system-wall-clock-ms.h Tue Dec 09 13:17:49 2014 -0800 @@ -23,14 +23,31 @@ #include +/** + * \file + * \ingroup system + * System-independent wall clock class ns3::SystemWallClockMs declaration. + */ + namespace ns3 { /** - * \addtogroup core - * \see SystemWallClockMs + * @ingroup core + * @defgroup system System Services + * + * System-independent interfaces to operating system services: + * files system, threading, wall clock time. + * + * Services provided: + * + * - File and directory paths. + * - Thread primitives: threads, conditional waits, mutex, critical sections. + * - Asynchronous input from a file descriptor. + * - Wall clock time. */ + /** - * \ingroup testing + * \ingroup system * \brief Measure elapsed wall clock time in milliseconds. */ class SystemWallClockMs { diff -r e57bfdb4f12c -r caafe12b0378 src/core/model/unix-fd-reader.h --- a/src/core/model/unix-fd-reader.h Sun Dec 07 22:08:04 2014 -0800 +++ b/src/core/model/unix-fd-reader.h Tue Dec 09 13:17:49 2014 -0800 @@ -27,9 +27,16 @@ #include "system-thread.h" #include "event-id.h" +/** + * \ingroup system + * \file + * Asynchronous reads from a file descriptor, which trigger a Callback. + */ + namespace ns3 { /** + * \ingroup system * \brief A class that asynchronously reads from a file descriptor. * * This class can be used to start a system thread that reads from a @@ -40,7 +47,9 @@ class FdReader : public SimpleRefCount { public: + /** Constructor. */ FdReader(); + /** Destructor. */ virtual ~FdReader(); /** @@ -66,9 +75,18 @@ */ struct Data { + /** Default constructor, with null buffer and zero length. */ Data () : m_buf (0), m_len (0) {} + /** + * Construct from a buffer of a given length. + * + * \param buf The buffer. + * \param len The size of the buffer, in bytes. + */ Data (uint8_t *buf, ssize_t len) : m_buf (buf), m_len (len) {} + /** The read data buffer. */ uint8_t *m_buf; + /** The size of the read data buffer, in bytes. */ ssize_t m_len; }; @@ -94,13 +112,26 @@ private: + /** The asynchronous function which performs the read. */ void Run (void); + /** Event handler scheduled for destroy time to halt the thread. */ void DestroyEvent (void); + /** The main thread callback function to invoke when we have data. */ Callback m_readCallback; + + /** The thread doing the read, created and launched by Start(). */ Ptr m_readThread; - int m_evpipe[2]; // pipe used to signal events between threads - bool m_stop; // true means the read thread should stop + + /** Pipe used to signal events between threads. */ + int m_evpipe[2]; + /** Signal the read thread to stop. */ + bool m_stop; + + /** + * The event scheduled for destroy time which will invoke DestroyEvent + * and halt the thread. + */ EventId m_destroyEvent; }; diff -r e57bfdb4f12c -r caafe12b0378 src/core/model/unix-system-condition.cc --- a/src/core/model/unix-system-condition.cc Sun Dec 07 22:08:04 2014 -0800 +++ b/src/core/model/unix-system-condition.cc Tue Dec 09 13:17:49 2014 -0800 @@ -25,28 +25,66 @@ #include "log.h" +/** + * \file + * \ingroup thread + * Thread conditional wait implementation for Unix-like systems. + */ + namespace ns3 { NS_LOG_COMPONENT_DEFINE ("SystemCondition"); +/** + * \ingroup thread + * Implementation of SystemCondition for Unix-like systems. + */ class SystemConditionPrivate { public: /// Conversion from ns to s. static const uint64_t NS_PER_SEC = (uint64_t)1000000000; + /** Constructor. */ SystemConditionPrivate (); + /** Destructor. */ ~SystemConditionPrivate (); - + + /** + * Set the condition. + * + * \param condition The new condition value. + */ void SetCondition (bool condition); + /** + * Get the condition value. + * + * \returns The condition value. + */ bool GetCondition (void); + /** Signal the condition. */ void Signal (void); + /** Broadcast the condition. */ void Broadcast (void); + /** + * Unset the condition, then wait for another thread + * to set it with SetCondition. */ void Wait (void); + /** + * Unset the condition, then wait for a limited amount of wall-clock + * time for another thread to set it with SetCondition. + * + * \param ns Maximum time to wait, in ns. + * \returns \c true if the condition timed out; \c false if the other + * thread set it. + */ bool TimedWait (uint64_t ns); private: + /** Mutex controlling access to the condition. */ pthread_mutex_t m_mutex; + /** The pthread condition variable. */ pthread_cond_t m_cond; + /** The condition state. */ bool m_condition; }; diff -r e57bfdb4f12c -r caafe12b0378 src/core/model/unix-system-mutex.cc --- a/src/core/model/unix-system-mutex.cc Sun Dec 07 22:08:04 2014 -0800 +++ b/src/core/model/unix-system-mutex.cc Tue Dec 09 13:17:49 2014 -0800 @@ -27,19 +27,26 @@ #include "log.h" +/** + * @file + * @ingroup thread + * Mutex critical section primitive definitions for Unix-like systems. + */ + namespace ns3 { NS_LOG_COMPONENT_DEFINE_MASK ("SystemMutex", ns3::LOG_PREFIX_TIME); +/** System-dependent implementation of SystemMutex. */ class SystemMutexPrivate { public: - SystemMutexPrivate (); + SystemMutexPrivate (); ~SystemMutexPrivate (); - void Lock (void); - void Unlock (void); + void Lock (void); /**< Acquire ownership of the mutex. */ + void Unlock (void); /**< Release ownership of the mutex. */ private: - pthread_mutex_t m_mutex; + pthread_mutex_t m_mutex; /**< The mutex. */ }; SystemMutexPrivate::SystemMutexPrivate () diff -r e57bfdb4f12c -r caafe12b0378 src/core/model/unix-system-wall-clock-ms.cc --- a/src/core/model/unix-system-wall-clock-ms.cc Sun Dec 07 22:08:04 2014 -0800 +++ b/src/core/model/unix-system-wall-clock-ms.cc Tue Dec 09 13:17:49 2014 -0800 @@ -24,12 +24,19 @@ #include #include +/** + * \file + * \ingroup system + * Wall clock class ns3::SystemWallClockMs implementation + * for Unix-like systems. + */ + namespace ns3 { NS_LOG_COMPONENT_DEFINE ("SystemWallClockMsPrivate"); /** - * \ingroup testingimpl + * \ingroup system * \brief System-dependent implementation for SystemWallClockMs */ class SystemWallClockMsPrivate { diff -r e57bfdb4f12c -r caafe12b0378 src/core/model/win32-system-wall-clock-ms.cc --- a/src/core/model/win32-system-wall-clock-ms.cc Sun Dec 07 22:08:04 2014 -0800 +++ b/src/core/model/win32-system-wall-clock-ms.cc Tue Dec 09 13:17:49 2014 -0800 @@ -22,10 +22,17 @@ #include +/** + * \file + * \ingroup system + * Wall clock class ns3::SystemWallClockMs implementation + * for Windows-32 systems. + */ + namespace ns3 { /** - * \ingroup testingimpl + * \ingroup system * \brief System-dependent implementation for SystemWallClockMs */ class SystemWallClockMsPrivate {