Merge remote-tracking branch 'origin/main' into houliston/changingstuff

docs/extension.rst

@@ -156,11 +156,11 @@ The template is used to have multiple static contexts.
 
         using task_ptr = std::unique_ptr<threading::ReactionTask>;
 
-        /// our queue which sorts tasks by priority
+        /// Our queue which sorts tasks by priority
         static std::priority_queue<task_ptr> queue;
-        /// how many tasks are currently running
+        /// How many tasks are currently running
         static volatile bool running;
-        /// a mutex to ensure data consistency
+        /// A mutex to ensure data consistency
         static std::mutex mutex;
 
 Now we define the `reschedule` to interrupt any new tasks if we are currently running. Recall that NUClear is

src/LogLevel.hpp

@@ -58,8 +58,8 @@ enum LogLevel : uint8_t {
      * Debug contains messages that represent the inputs and outputs of different computation units.
      *
      * If you have a function that performs three steps to do something then it's likely that you will have a message
-     * for the input and output of those three steps. Additionally you would likely have messages that check if it hit
-     * different branches.
+     * for the input and output of those three steps.
+     * Additionally you would likely have messages that check if it hit different branches.
      */
     DEBUG,
 
@@ -75,26 +75,25 @@ enum LogLevel : uint8_t {
      * The warning level is used to notify us that everything might not be working perfectly.
      *
      * Warnings are errors or inconsistencies that aren't fatal and generally do not completely break the system.
-     * However a warning message should require action from someone and should point to a section of the system that
-     * needs attention.
+     * However a warning message should require action and should point to a section of the system that needs attention.
      */
     WARN,
 
     /**
      * The error level is used to report unexpected behavior.
-     *
+
      * This level doesn't need to prefix a program-crashing issue but should be used to report major unexpected branches
-     * in logic or other constraint breaking problems such as failed assertions. All errors should require action from
-     * someone and should be addressed immediately.
+     * in logic or other constraint breaking problems such as failed assertions.
+     * All errors should require action from someone and should be addressed immediately.
      */
     ERROR,
 
     /**
      * Fatal is a program destroying error that needs to be addressed immediately.
      *
      * If a fatal message is sent it should point to something that should never ever happen and ideally provide as much
-     * information as possible as to why it crashed. Fatal messages require action immediately and should always be
-     * addressed.
+     * information as possible as to why it crashed.
+     * Fatal messages require action immediately and should always be addressed.
      */
     FATAL
 };

src/PowerPlant.hpp

@@ -61,9 +61,9 @@ namespace dsl {
 /**
  * The PowerPlant is the core of a NUClear system. It holds all Reactors in it and manages their communications.
  *
- * At the centre of every NUClear system is a PowerPlant. A PowerPlant contains all of the reactors that are
- * used within the system and sets up their reactions. It is also responsible for storing information between
- * reactions and ensuring that all threading is handled appropriately.
+ * At the centre of every NUClear system is a PowerPlant.
+ * A PowerPlant contains all of the reactors that are used within the system and sets up their reactions.
+ * It is also responsible for storing information between reactions and ensuring threading is handled appropriately.
  */
 class PowerPlant {
     // Reactors and PowerPlants are very tightly linked
@@ -95,9 +95,9 @@ class PowerPlant {
      *
      * Arguments passed to this function will be emitted as a CommandLineArguments message.
      *
-     * @param config    The PowerPlant's configuration
-     * @param argc      The number of command line arguments
-     * @param argv      The command line argument strings
+     * @param config The PowerPlant's configuration
+     * @param argc   The number of command line arguments
+     * @param argv   The command line argument strings
      */
     // NOLINTNEXTLINE(cppcoreguidelines-avoid-c-arrays,modernize-avoid-c-arrays)
     PowerPlant(Configuration config = Configuration(), int argc = 0, const char* argv[] = nullptr);
@@ -112,18 +112,21 @@ class PowerPlant {
     /**
      * Starts up the PowerPlant's components in order and begins it running.
      *
-     * Starts up the PowerPlant instance and starts all the pool threads. This method is blocking and will release when
-     * the PowerPlant shuts down. It should only be called from the main thread so that statics are not destructed.
+     * Starts up the PowerPlant instance and starts all the pool threads.
+     * This method is blocking and will release when the PowerPlant shuts down.
+     * It should only be called from the main thread so that statics are not destructed.
      */
     void start();
 
     /**
-     * Shuts down the PowerPlant, tells all component threads to terminate then releases the main thread.
+     * Shuts down the PowerPlant, tells all component threads to terminate and waits for them to finish.
      */
     void shutdown();
 
     /**
-     * Returns true if the PowerPlant is running or not intending to shut down soon. Returns false otherwise.
+     * Gets the current running state of the PowerPlant.
+     *
+     * @return `true` if the PowerPlant is running, `false` if it is shut down, or is in the process of shutting down.
      */
     bool running() const;
 
@@ -133,11 +136,11 @@ class PowerPlant {
      * This function constructs a new Reactor of the template type.
      * It passes the specified LogLevel in the environment of that reactor so that it can be used to filter logs.
      *
-     * @tparam T        The type of the reactor to build and install
-     * @tparam Args     The types of the extra arguments to pass to the reactor constructor
-     * @tparam level    The initial logging level for this reactor to use
+     * @tparam T     The type of the reactor to build and install
+     * @tparam Args  The types of the extra arguments to pass to the reactor constructor
+     * @tparam level The initial logging level for this reactor to use
      *
-     * @param arg       Extra arguments to pass to the reactor constructor
+     * @param arg Extra arguments to pass to the reactor constructor
      *
      * @return A reference to the installed reactor
      */
@@ -158,8 +161,8 @@ class PowerPlant {
      * Adds an idle task to the task scheduler.
      *
      * This function adds an idle task to the task scheduler, which will be executed when the thread pool associated
-     * with the given `pool_id` has no other tasks to execute. The `task` parameter is a Reaction from which a task will
-     * be submitted when the pool is idle.
+     * with the given `pool_id` has no other tasks to execute.
+     * The `task` parameter is a Reaction from which a task will be submitted when the pool is idle.
      *
      * @param pool_descriptor The descriptor for the thread pool to test for idle
      * @param reaction        The reaction to be executed when idle
@@ -181,8 +184,8 @@ class PowerPlant {
     /**
      * Submits a new task to the ThreadPool to be queued and then executed.
      *
-     * @param task The Reaction task to be executed in the thread pool
-     * @param immediate if this task should run immediately in the current thread
+     * @param task      The Reaction task to be executed in the thread pool
+     * @param immediate If this task should run immediately in the current thread
      */
     void submit(std::unique_ptr<threading::ReactionTask>&& task, const bool& immediate = false) noexcept;
 
@@ -267,20 +270,22 @@ class PowerPlant {
     /**
      * Emits data to the system and routes it to the other systems that use it.
      *
-     * This is for the special case of emitting a shared_ptr. The types are Fused and the reaction is started.
+     * This is for the special case of emitting a shared_ptr.
+     * The types are Fused and the reaction is started.
      * If the Fusion fails, a static_assert fails.
      *
-     * @note Emitting shared data can be helpful for forwarding data which has already been emitted and forwarding it on
-     * to external parties, without needing to copy it.
+     * @note
+     *  Emitting shared data can be helpful for forwarding data which has already been emitted and forwarding it on to
+     *  external parties, without needing to copy it.
      *
      * @see NUClear::util::FunctionFusion
      *
      * @warning This shouldn't be used without a specific reason - usually forwarding data.
      *
-     * @tparam First        The first handler to use for this emit
-     * @tparam Remainder    The remaining handlers to use for this emit
-     * @tparam T            The type of the data that we are emitting
-     * @tparam Arguments    The additional arguments that will be provided to the handlers
+     * @tparam First     The first handler to use for this emit
+     * @tparam Remainder The remaining handlers to use for this emit
+     * @tparam T         The type of the data that we are emitting
+     * @tparam Arguments The additional arguments that will be provided to the handlers
      *
      * @param data The data we are emitting
      */
@@ -335,7 +340,7 @@ class PowerPlant {
 };
 
 /**
- * This free floating log function can be called from anywhere and will use the singleton PowerPlant
+ * This free floating log function can be called from anywhere and will use the singleton PowerPlant.
  *
  * @see NUClear::PowerPlant::log()
  *

src/Reactor.hpp

@@ -134,8 +134,10 @@ namespace dsl {
 /**
  * Base class for any system that wants to react to events/data from the rest of the system.
  *
- * Provides functionality for binding callbacks to incoming data events. Callbacks are executed
- * in a transparent, multithreaded manner. TODO needs to be expanded and updated
+ * Provides functionality for binding callbacks to incoming data events.
+ * Callbacks are executed in a transparent, multithreaded manner.
+ *
+ * TODO needs to be expanded and updated.
  */
 class Reactor {
 public:
@@ -172,8 +174,8 @@ class Reactor {
 
     /***************************************************************************************************************
      * The types here are imported from other contexts so that when extending from the Reactor type in normal      *
-     * usage there does not need to be any namespace declarations on the used types. This affords a simpler API    *
-     * for the user.                                                                                               *
+     * usage there does not need to be any namespace declarations on the used types.                               *
+     * This affords a simpler API for the user.                                                                    *
      **************************************************************************************************************/
 
     /// @copydoc dsl::word::Trigger
@@ -358,8 +360,8 @@ class Reactor {
     /**
      * The on function is the method used to create a reaction in the NUClear system.
      *
-     * This function is used to create a Reaction in the system. By providing the correct template parameters, this
-     * function can modify how and when this reaction runs.
+     * This function is used to create a Reaction in the system.
+     * By providing the correct template parameters, this function can modify how and when this reaction runs.
      *
      * @tparam DSL          The NUClear domain specific language information
      * @tparam Arguments    The types of the arguments passed into the function
@@ -381,8 +383,8 @@ class Reactor {
      * Emits data into the system so that other reactors can use it.
      *
      * This function emits data to the rest of the system so that it can be used.
-     * This results in it being the new data used when a with is used, and triggering
-     * any reaction that is set to be triggered on this data type.
+     * This results in it being the new data used when a with is used, and triggering any reaction that is set to be
+     * triggered on this data type.
      *
      * @tparam Handlers The handlers for this emit (e.g. LOCAL, NETWORK etc)
      * @tparam T        The type of the data we are emitting, for some handlers (e.g. WATCHDOG) this is optional

src/clock.hpp

@@ -43,32 +43,50 @@ struct clock : public NUCLEAR_CLOCK_TYPE {
 
     /**
      * Get the current time of the clock.
+     *
      * @return The current time of the clock.
      */
     static time_point now();
 
     /**
      * Adjust the clock by a specified duration and real-time factor.
+     *
      * @param adjustment The duration by which to adjust the clock.
-     * @param rtf The real-time factor to apply to the clock.
+     * @param rtf        The real-time factor to apply to the clock.
      */
     static void adjust_clock(const duration& adjustment, const double& rtf = 1.0);
 
     /**
      * Set the clock to a specified time and real-time factor.
+     *
      * @param time The time to set the clock to.
-     * @param rtf The real-time factor to apply to the clock.
+     * @param rtf  The real-time factor to apply to the clock.
      */
     static void set_clock(const time_point& time, const double& rtf = 1.0);
 
 
     /**
      * Get the real-time factor of the clock.
-     * @return The real-time factor of the clock.
+     *
+     * @return The real-time factor of the clock
      */
     static double rtf();
 
 private:
+    /**
+     * Convert a duration to the clock's duration type.
+     *
+     * @tparam T The type of the duration.
+     *
+     * @param t The duration to convert.
+     *
+     * @return The converted duration.
+     */
+    template <typename T>
+    duration static dc(const T& t) {
+        return std::chrono::duration_cast<duration>(t);
+    }
+
     /**
      * Data structure to hold clock information.
      */
@@ -83,13 +101,13 @@ struct clock : public NUCLEAR_CLOCK_TYPE {
         ClockData() = default;
     };
 
-    /// The mutex to protect the clock data.
+    /// The mutex to protect the clock data
     static std::mutex mutex;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
 
-    /// The clock data for the system.
+    /// The clock data for the system
     static std::array<ClockData, 3> data;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
 
-    /// The active clock data index.
+    /// The active clock data index
     static std::atomic<int> active;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
 };
 

src/dsl/fusion/BindFusion.hpp

@@ -32,7 +32,7 @@ namespace dsl {
     namespace fusion {
 
         /**
-         * This is our Function Fusion wrapper class that allows it to call bind functions
+         * This is our Function Fusion wrapper class that allows it to call bind functions.
          *
          * @tparam Function the bind function that we are wrapping for
          * @tparam DSL      the DSL that we pass to our bind function
@@ -41,7 +41,8 @@ namespace dsl {
         struct BindCaller {
 
             /**
-             * This struct is used if there is a return type. It just passes the returned data back up.
+             * This struct is used if there is a return type.
+             * It just passes the returned data back up.
              *
              * @return the data that is returned by the bind call
              */
@@ -53,8 +54,8 @@ namespace dsl {
             };
 
             /**
-             * This struct is used if the return type of the bind function is void. It wraps it into an empty
-             * tuple instead.
+             * This struct is used if the return type of the bind function is void.
+             * It wraps it into an empty tuple instead.
              *
              * @return an empty tuple
              */
@@ -87,11 +88,11 @@ namespace dsl {
         struct BindWords;
 
         /**
-         * Metafunction that extracts all of the Words with a bind function
+         * Metafunction that extracts all of the Words with a bind function.
          *
-         * @tparam Word1        The word we are looking at
-         * @tparam WordN        The words we have yet to look at
-         * @tparam FoundWords   The words we have found with bind functions
+         * @tparam Word1      The word we are looking at
+         * @tparam WordN      The words we have yet to look at
+         * @tparam FoundWords The words we have found with bind functions
          */
         template <typename Word1, typename... WordN, typename... FoundWords>
         struct BindWords<std::tuple<Word1, WordN...>, std::tuple<FoundWords...>>

src/dsl/fusion/GetFusion.hpp

@@ -33,7 +33,7 @@ namespace dsl {
     namespace fusion {
 
         /**
-         * This is our Function Fusion wrapper class that allows it to call get functions
+         * This is our Function Fusion wrapper class that allows it to call get functions.
          *
          * @tparam Function the get function that we are wrapping for
          * @tparam DSL      the DSL that we pass to our get function
@@ -49,7 +49,7 @@ namespace dsl {
         struct GetWords;
 
         /**
-         * Metafunction that extracts all of the Words with a get function
+         * Metafunction that extracts all of the Words with a get function.
          *
          * @tparam Word1    the word we are looking at
          * @tparam WordN    the words we have yet to look at
@@ -62,7 +62,7 @@ namespace dsl {
                                         /*F*/ GetWords<std::tuple<WordN...>, std::tuple<FoundWords...>>> {};
 
         /**
-         * Termination case for the GetWords metafunction
+         * Termination case for the GetWords metafunction.
          *
          * @tparam GetWords The words we have found with get functions
          */