From a8d5f4f672187d43a1a00a1d32f1f8d7fff8d2c0 Mon Sep 17 00:00:00 2001 From: Neelamagam Date: Mon, 29 Jan 2024 13:12:45 -0500 Subject: [PATCH 1/3] Doxygen document for the files: configGraphOutput.h, cputimer.h, event.h, exit.h, linkPair.h --- src/sst/core/configGraphOutput.h | 18 ++++++++++++++++++ src/sst/core/cputimer.h | 3 +++ src/sst/core/event.h | 1 + src/sst/core/exit.h | 22 ++++++++++++++++++++-- src/sst/core/linkPair.h | 17 +++++++++++++---- 5 files changed, 55 insertions(+), 6 deletions(-) diff --git a/src/sst/core/configGraphOutput.h b/src/sst/core/configGraphOutput.h index 4bf322c54..fb42bf6a0 100644 --- a/src/sst/core/configGraphOutput.h +++ b/src/sst/core/configGraphOutput.h @@ -23,6 +23,10 @@ class ConfigGraph; namespace Core { +/** + * Exception handler class for graph configuration. + * Provides the interface to handle errors through the throw exception. +*/ class ConfigGraphOutputException : public std::exception { public: @@ -32,12 +36,21 @@ class ConfigGraphOutputException : public std::exception std::strcpy(exMsg, msg); } + /** + * @return Exception Message + */ virtual const char* what() const noexcept override { return exMsg; } +/** + * Exception message generated on call. +*/ protected: char* exMsg; }; +/** + * Outputs configuration data to a specified file path. +*/ class ConfigGraphOutput { public: @@ -45,6 +58,11 @@ class ConfigGraphOutput virtual ~ConfigGraphOutput() { fclose(outputFile); } + /** + * @param cfg Constant pointer to SST configuration + * @param graph Constant pointer to SST configuration graph + * @return void + */ virtual void generate(const Config* cfg, ConfigGraph* graph) = 0; protected: diff --git a/src/sst/core/cputimer.h b/src/sst/core/cputimer.h index a2d850699..9ca7e025d 100644 --- a/src/sst/core/cputimer.h +++ b/src/sst/core/cputimer.h @@ -14,6 +14,9 @@ #include +/** + * @return Current CPU time using the time of day. Timezone information is not filled. +*/ double sst_get_cpu_time(); #endif // SST_CORE_CPU_TIMER_H diff --git a/src/sst/core/event.h b/src/sst/core/event.h index cb096a0fe..adb639b08 100644 --- a/src/sst/core/event.h +++ b/src/sst/core/event.h @@ -155,6 +155,7 @@ class Event : public Activity For links that are going to a sync, the delivery_info is used on the remote side to send the event on the proper link. For local links, delivery_info contains the delivery functor. + @return void */ inline void setDeliveryInfo(LinkId_t tag, uintptr_t delivery_info) { diff --git a/src/sst/core/exit.h b/src/sst/core/exit.h index cc8966bfa..52e5bfdfa 100644 --- a/src/sst/core/exit.h +++ b/src/sst/core/exit.h @@ -36,8 +36,8 @@ class Exit : public Action public: /** * Create a new ExitEvent - * @param sim - Simulation Object - * @param single_rank - True if there are no parallel ranks + * @param sim Simulation object + * @param single_rank True if there are no parallel ranks * * Exit needs to register a handler during constructor time, which * requires a simulation object. But the simulation class creates @@ -56,13 +56,30 @@ class Exit : public Action bool refDec(ComponentId_t, uint32_t thread); unsigned int getRefCount(); + + /** Gets the end time of the simulation + * @return Time when simulation ends + */ SimTime_t getEndTime() { return end_time; } + + /** Stores the time the simulation has ended + * @param time Current simulation time + * @return void + */ void setEndTime(SimTime_t time) { end_time = time; } + /** Computes the end time of the simulation + * @return End time of the simulation + */ SimTime_t computeEndTime(); void execute(void) override; void check(); + /** + * @param header String to preface the exit action log + * @param out SST Output logger object + * @return void + */ void print(const std::string& header, Output& out) const override { out.output( @@ -70,6 +87,7 @@ class Exit : public Action getPriority()); } + unsigned int getGlobalCount() { return global_count; } private: diff --git a/src/sst/core/linkPair.h b/src/sst/core/linkPair.h index 2c80e0c73..8a7b164bb 100644 --- a/src/sst/core/linkPair.h +++ b/src/sst/core/linkPair.h @@ -23,7 +23,9 @@ namespace SST { class LinkPair { public: - /** Create a new LinkPair. This is used when the endpoints are in the same partition. */ + /** Create a new LinkPair. This is used when the endpoints are in the same partition. + * @param order Value used to enforce the link order. + */ LinkPair(LinkId_t order) : left(new Link(order)), right(new Link(order)) { my_id = order; @@ -32,7 +34,10 @@ class LinkPair right->pair_link = left; } - /** Create a new LinkPair. This is used when the endpoints are in different partitions. */ + /** Create a new LinkPair. This is used when the endpoints are in different partitions. + * @param order Value used to enforce the link order. + * @param remote_tag Used to look up the correct link on the other side. + */ LinkPair(LinkId_t order, LinkId_t remote_tag) : left(new Link(remote_tag)), right(new Link(order)) { my_id = order; @@ -43,10 +48,14 @@ class LinkPair virtual ~LinkPair() {} - /** Return the Left Link */ + /** Return the Left Link + * @return Left link + */ inline Link* getLeft() { return left; } - /** Return the Right Link */ + /** Return the Right Link + * @return Right link + */ inline Link* getRight() { return right; } private: From bda4ffef921386b101ff74dc3ff2d62bf8f33754 Mon Sep 17 00:00:00 2001 From: Neelamagam Date: Tue, 30 Jan 2024 09:33:32 -0500 Subject: [PATCH 2/3] Fixing formatting to pass clang-format test --- src/sst/core/configGraphOutput.h | 14 +++++++------- src/sst/core/cputimer.h | 2 +- src/sst/core/exit.h | 12 ++++++------ src/sst/core/linkPair.h | 16 ++++++++-------- 4 files changed, 22 insertions(+), 22 deletions(-) diff --git a/src/sst/core/configGraphOutput.h b/src/sst/core/configGraphOutput.h index fb42bf6a0..754e971ca 100644 --- a/src/sst/core/configGraphOutput.h +++ b/src/sst/core/configGraphOutput.h @@ -26,7 +26,7 @@ namespace Core { /** * Exception handler class for graph configuration. * Provides the interface to handle errors through the throw exception. -*/ + */ class ConfigGraphOutputException : public std::exception { public: @@ -38,19 +38,19 @@ class ConfigGraphOutputException : public std::exception /** * @return Exception Message - */ + */ virtual const char* what() const noexcept override { return exMsg; } -/** - * Exception message generated on call. -*/ + /** + * Exception message generated on call. + */ protected: char* exMsg; }; /** * Outputs configuration data to a specified file path. -*/ + */ class ConfigGraphOutput { public: @@ -62,7 +62,7 @@ class ConfigGraphOutput * @param cfg Constant pointer to SST configuration * @param graph Constant pointer to SST configuration graph * @return void - */ + */ virtual void generate(const Config* cfg, ConfigGraph* graph) = 0; protected: diff --git a/src/sst/core/cputimer.h b/src/sst/core/cputimer.h index 9ca7e025d..bd6f9a260 100644 --- a/src/sst/core/cputimer.h +++ b/src/sst/core/cputimer.h @@ -16,7 +16,7 @@ /** * @return Current CPU time using the time of day. Timezone information is not filled. -*/ + */ double sst_get_cpu_time(); #endif // SST_CORE_CPU_TIMER_H diff --git a/src/sst/core/exit.h b/src/sst/core/exit.h index 52e5bfdfa..11942e0fc 100644 --- a/src/sst/core/exit.h +++ b/src/sst/core/exit.h @@ -59,18 +59,18 @@ class Exit : public Action /** Gets the end time of the simulation * @return Time when simulation ends - */ - SimTime_t getEndTime() { return end_time; } + */ + SimTime_t getEndTime() { return end_time; } /** Stores the time the simulation has ended * @param time Current simulation time * @return void - */ - void setEndTime(SimTime_t time) { end_time = time; } + */ + void setEndTime(SimTime_t time) { end_time = time; } /** Computes the end time of the simulation * @return End time of the simulation - */ + */ SimTime_t computeEndTime(); void execute(void) override; void check(); @@ -79,7 +79,7 @@ class Exit : public Action * @param header String to preface the exit action log * @param out SST Output logger object * @return void - */ + */ void print(const std::string& header, Output& out) const override { out.output( diff --git a/src/sst/core/linkPair.h b/src/sst/core/linkPair.h index 8a7b164bb..ca761bb5b 100644 --- a/src/sst/core/linkPair.h +++ b/src/sst/core/linkPair.h @@ -23,9 +23,9 @@ namespace SST { class LinkPair { public: - /** Create a new LinkPair. This is used when the endpoints are in the same partition. + /** Create a new LinkPair. This is used when the endpoints are in the same partition. * @param order Value used to enforce the link order. - */ + */ LinkPair(LinkId_t order) : left(new Link(order)), right(new Link(order)) { my_id = order; @@ -34,10 +34,10 @@ class LinkPair right->pair_link = left; } - /** Create a new LinkPair. This is used when the endpoints are in different partitions. + /** Create a new LinkPair. This is used when the endpoints are in different partitions. * @param order Value used to enforce the link order. * @param remote_tag Used to look up the correct link on the other side. - */ + */ LinkPair(LinkId_t order, LinkId_t remote_tag) : left(new Link(remote_tag)), right(new Link(order)) { my_id = order; @@ -48,14 +48,14 @@ class LinkPair virtual ~LinkPair() {} - /** Return the Left Link + /** Return the Left Link * @return Left link - */ + */ inline Link* getLeft() { return left; } - /** Return the Right Link + /** Return the Right Link * @return Right link - */ + */ inline Link* getRight() { return right; } private: From 26e110205e6794cf11c4e085fc2b1cf67bf40a34 Mon Sep 17 00:00:00 2001 From: Neelamagam Date: Mon, 12 Feb 2024 14:26:23 -0500 Subject: [PATCH 3/3] Additional documentation for the files: action.h, sstinfo.h, stringize.h, timeConverter.h, timeLord.h, unitAlgebra.h --- src/sst/core/action.h | 3 +++ src/sst/core/sstinfo.h | 27 ++++++++++++++++++++++----- src/sst/core/stringize.h | 2 +- src/sst/core/timeConverter.h | 9 ++++----- src/sst/core/timeLord.h | 8 ++++---- src/sst/core/unitAlgebra.h | 22 ++++++++++++---------- 6 files changed, 46 insertions(+), 25 deletions(-) diff --git a/src/sst/core/action.h b/src/sst/core/action.h index 2e870263c..67d6a7131 100644 --- a/src/sst/core/action.h +++ b/src/sst/core/action.h @@ -32,6 +32,9 @@ class Action : public Activity protected: /** Called to signal to the Simulation object to end the simulation */ void endSimulation(); + /** Called to signal to the Simulation object to end the simulation + * @param end Simulation cycle when the simulation finishes + */ void endSimulation(SimTime_t end); NotSerializable(SST::Action) diff --git a/src/sst/core/sstinfo.h b/src/sst/core/sstinfo.h index 00494e3f0..0c8338b43 100644 --- a/src/sst/core/sstinfo.h +++ b/src/sst/core/sstinfo.h @@ -56,19 +56,22 @@ class SSTInfoConfig : public ConfigShared /** Clears the current filter map */ void clearFilterMap() { m_filters.clear(); } - /** Return the filter map */ + /** @return Filter map */ FilterMap_t& getFilterMap() { return m_filters; } - /** Return the bit field of various command line options enabled. */ + /** @return Bit field of various command line options enabled. */ unsigned int getOptionBits() { return m_optionBits; } - /** Return the user defined path the XML File. */ + /** @return User defined path the XML File. */ std::string& getXMLFilePath() { return m_XMLFilePath; } - /** Is debugging output enabled? */ + /** @return True if the debugging output is enabled, otherwise False */ bool debugEnabled() const { return m_debugEnabled; } + /** @return True if the m_filter multimap is emtpy, otherwise False */ bool processAllElements() const { return m_filters.empty(); } + /** @return True if command line options are enabled and verbose configuration is valid, otherwise False */ bool doVerbose() const { return m_optionBits & CFG_VERBOSE; } + /** @return True if interactive is enabled, otherwise False */ bool interactiveEnabled() const { return m_interactive; } void addFilter(const std::string& name); @@ -191,10 +194,24 @@ class SSTLibraryInfo /** Set filters based on search term */ void filterSearch(std::stringstream& outputStream, std::string tag, std::string searchTerm); - /** Filter output from info map*/ + /** Filter output from info map + * @return True if the library filter is defined, otherwise False + */ bool getFilter() { return m_libraryFilter; } + /** + * Clears the component filter and sets the internal library filter status + * @param libFilter + */ void resetFilters(bool libFilter) { m_libraryFilter = libFilter, m_componentFilters.clear(); } + /** + * Sets the internal library filter status + * @param libFilter + */ void setLibraryFilter(bool filter) { m_libraryFilter = filter; } + /** + * Adds the component filter string to the end of the internal vector of components + * @param component + */ void setComponentFilter(std::string component) { m_componentFilters.push_back(component); } template diff --git a/src/sst/core/stringize.h b/src/sst/core/stringize.h index 57986ff81..d90a40322 100644 --- a/src/sst/core/stringize.h +++ b/src/sst/core/stringize.h @@ -102,7 +102,7 @@ struct escaped_list_separator {} /** - * @return pair = + * Sets pair = */ void operator()(iter& first, iter last, std::string& token) { diff --git a/src/sst/core/timeConverter.h b/src/sst/core/timeConverter.h index 27385edba..69caa8013 100644 --- a/src/sst/core/timeConverter.h +++ b/src/sst/core/timeConverter.h @@ -31,25 +31,24 @@ class TimeConverter public: /** Converts from the component's view to the core's view of time. - \param time time to convert to core time + @param time time to convert to core time */ SimTime_t convertToCoreTime(SimTime_t time) const { return time * factor; } /** Converts from the core's view to the components's view of time. The result is truncated, not rounded. - \param time time to convert from core time + @param time time to convert from core time */ SimTime_t convertFromCoreTime(SimTime_t time) const { return time / factor; } /** - * Return the factor used for conversions with Core Time + * @return The factor used for conversions with Core Time */ SimTime_t getFactor() const { return factor; } /** - Return the period represented by this TimeConverter as a - UnitAlgebra + @return The period represented by this TimeConverter as a UnitAlgebra */ UnitAlgebra getPeriod() const; // Implemented in timeLord.cc diff --git a/src/sst/core/timeLord.h b/src/sst/core/timeLord.h index 0f92db4d4..a6619c3ab 100644 --- a/src/sst/core/timeLord.h +++ b/src/sst/core/timeLord.h @@ -60,15 +60,15 @@ class TimeLord TimeConverter* getTimeConverter(const UnitAlgebra& ts); /** - * Return the Time Base of the TimeLord + * @return Time Base of the TimeLord */ UnitAlgebra getTimeBase() const { return timeBase; } - /** Return a TimeConverter which represents Nanoseconds */ + /** @return TimeConverter which represents Nanoseconds */ TimeConverter* getNano() { return nano; } - /** Return a TimeConverter which represents Microseconds */ + /** @return TimeConverter which represents Microseconds */ TimeConverter* getMicro() { return micro; } - /** Return a TimeConverter which represents Milliseconds */ + /** @return TimeConverter which represents Milliseconds */ TimeConverter* getMilli() { return milli; } /** Not a Public API. diff --git a/src/sst/core/unitAlgebra.h b/src/sst/core/unitAlgebra.h index 415f89e3d..4a468f447 100644 --- a/src/sst/core/unitAlgebra.h +++ b/src/sst/core/unitAlgebra.h @@ -70,8 +70,8 @@ class Units // Non-static data members and functions /** Create a new instantiation of a Units with a base unit string, and multiplier - * \param units String representing the new unit - * \param multiplier Value by which to multiply to get to this unit + * @param units String representing the new unit + * @param multiplier Value by which to multiply to get to this unit */ Units(const std::string& units, sst_big_num& multiplier); Units() {} @@ -120,8 +120,8 @@ class UnitAlgebra : /** Create a new UnitAlgebra instance, and pre-populate with a parsed value. - \param val Value to parse. It is of the following format: - \code + @param val Value to parse. It is of the following format: + @code val := NUMBER( )?UNITS NUMBER := (-)?[0-9]+(.[0-9]+)? UNITS := UNITGROUP(/UNITGROUP) @@ -130,7 +130,7 @@ class UnitAlgebra : SIPREFIX := {a,f,p,n,u,m,[kKMGTPE]i?} BASEUNIT := {s,B,b,events} COMPUNIT := {Hz,hz,Bps,bps,event} - \endcode + @endcode */ UnitAlgebra(const std::string& val); virtual ~UnitAlgebra(); @@ -139,21 +139,23 @@ class UnitAlgebra : UnitAlgebra(const UnitAlgebra&) = default; /** Print to an ostream the value - * \param precision Number of digits to print. Default is 6. <= 0 is full precision. + * @param stream Output stream + * @param precision Number of digits to print. Default is 6. <= 0 is full precision. */ void print(std::ostream& stream, int32_t precision = 6); /** Print to an ostream the value * Formats the number using SI-prefixes - * \param precision Number of digits to print. Default is 6. <= 0 is full precision. + * @param stream Output stream + * @param precision Number of digits to print. Default is 6. <= 0 is full precision. */ void printWithBestSI(std::ostream& stream, int32_t precision = 6); /** Return a string representation of this value - * \param precision Number of digits to print. Default is 6. <= 0 is full precision. + * @param precision Number of digits to print. Default is 6. <= 0 is full precision. */ std::string toString(int32_t precision = 6) const; /** Return a string representation of this value * Formats the number using SI-prefixes - * \param precision Number of digits to print. Default is 6. <= 0 is full precision. + * @param precision Number of digits to print. Default is 6. <= 0 is full precision. */ std::string toStringBestSI(int32_t precision = 6) const; @@ -220,7 +222,7 @@ class UnitAlgebra : bool hasUnits(const std::string& u) const; /** Return the raw value */ sst_big_num getValue() const { return value; } - /** Return the rounded value as a 64bit integer */ + /** @return Rounded value as a 64bit integer */ int64_t getRoundedValue() const; double getDoubleValue() const; bool isValueZero() const;