#9 - Added Optional Callbacks for Thread (interfaces in IThread

Also added a Garbage Collection demo

Author: LK-Simon

examples/GarbageCollection/GarbageCollection.ino

@@ -0,0 +1,48 @@
+/*
+    An example of ESPressio Threads' Garbage Collection system in action.
+*/
+
+#define ESPRESSIO_THREAD_DEFAULT_STACK_SIZE = 1600 // This sets the default Stack Size for all Threads in the system.
+
+#include <Arduino.h>
+
+#include "ESPressio_IThread.hpp" // This gives us access to the `IThread` interface.
+#include "ESPressio_Thread.hpp" // This gives us access to our `Thread` base class.
+#include "ESPressio_ThreadManager.hpp" // This gives us access to the `ThreadManager` class.
+
+using namespace ESPressio::Threads;
+
+class DemoThread : public Thread {
+    private:
+        uint32_t _counter = 0;
+    protected:
+        void OnLoop() {
+            Serial.printf("DemoThread: %u\n", _counter++);
+            delay(1000);
+            if (counter == 10) { // When the counter reaches 10...
+                Terminate(); // ... terminate the thread.
+            }
+        }
+};
+
+DemoThread* thread;
+
+// This function will be called when the thread is destroyed.
+void onThreadDestroyed(IThread* thread) {
+    Serial.printf("Thread %u has been destroyed!\n", thread->GetThreadID()); // Print a message to the Serial Monitor.
+}
+
+void setup() {
+    Serial.begin(115200); // Start the Serial Monitor.
+
+    thread = new DemoThread(true); // Create a new instance of our `DemoThread` class. The `true` parameter tells the Thread to use Garbage Collection when it's Terminated!
+
+    thread.SetStartOnInitialize(true); // This will start the thread as soon as it's initialized. (true is the default, but we're setting it here for clarity.)
+    thread.SetOnDestroy(onThreadDestroyed); // This will set the `onThreadDestroyed` function as the callback for when the thread is destroyed.
+
+    ThreadManager::Initialize(); // This will initialize ALL Thread instances in your code!
+}
+
+void loop() {
+    // You can still use your main loop as normal, if you want to!
+}

examples/SimpleForeverThread copy/SimpleForeverThread.ino

@@ -0,0 +1,32 @@
+/*
+    An extremely simple example of an ESPressio Thread loop that runs on either core of the ESP32.
+*/
+
+#define ESPRESSIO_THREAD_DEFAULT_STACK_SIZE = 1600 // This sets the default Stack Size for all Threads in the system.
+
+#include <Arduino.h>
+
+#include "ESPressio_Thread.hpp"
+#include "ESPressio_ThreadManager.hpp"
+
+using namespace ESPressio::Threads;
+
+class DemoThread : public Thread {
+    private:
+        uint32_t _counter = 0;
+    protected:
+        void OnLoop() {
+            Serial.printf("DemoThread: %u\n", _counter++);
+            delay(1000);
+        }
+};
+
+DemoThread thread;
+
+void setup() {
+    Serial.begin(115200);
+
+    thread.SetStartOnInitialize(true);
+
+    ThreadManager::Initialize(); // This will initialize ALL Thread instances in your code!
+}

examples/SimpleForeverThread/SimpleForeverThread.ino

@@ -6,8 +6,9 @@
 
 #include <Arduino.h>
 
-#include "ESPressio_Thread.hpp"
-#include "ESPressio_ThreadManager.hpp"
+#include "ESPressio_IThread.hpp" // This gives us access to the `IThread` interface.
+#include "ESPressio_Thread.hpp" // This gives us access to our `Thread` base class.
+#include "ESPressio_ThreadManager.hpp" // This gives us access to the `ThreadManager` class.
 
 using namespace ESPressio::Threads;
 
@@ -24,9 +25,13 @@ class DemoThread : public Thread {
 DemoThread thread;
 
 void setup() {
-    Serial.begin(115200);
+    Serial.begin(115200); // Start the Serial Monitor.
 
-    thread.SetStartOnInitialize(true);
+    thread.SetStartOnInitialize(true); // This will start the thread as soon as it's initialized. (true is the default, but we're setting it here for clarity.)
 
     ThreadManager::Initialize(); // This will initialize ALL Thread instances in your code!
+}
+
+void loop() {
+    // You can still use your main loop as normal, if you want to!
 }

src/ESPressio_IThread.hpp

@@ -3,6 +3,7 @@
 // #define CORE_THREADING_DEBUG // Uncomment this to explicitly enable debugging for the threading module
 #include <Arduino.h>
 #include <cstdint>
+#include <functional>
 
 namespace ESPressio {
 
@@ -29,16 +30,12 @@ namespace ESPressio {
                 /// `Initialize` is invoked automatically for all Threads when the `ThreadManager` is initialized in your `main()` (or `setup()` for MCU projects) function.
                 virtual void Initialize() = 0;
 
-                /*
-                    `Terminate` is invoked automatically for all Threads when the `ThreadManager` is terminated in your `main()` (or `loop()` for MCU projects) function.
-                    You can, however, invoke it manually to terminate a Thread at any time!
-                */
+                /// `Terminate` is invoked automatically for all Threads when the `ThreadManager` is terminated in your `main()` (or `loop()` for MCU projects) function.
+                /// You can, however, invoke it manually to terminate a Thread at any time!
                 virtual void Terminate() = 0;
 
-                /*
-                    `Start` will start the Thread loop if it is not already running.
-                    It will also Resume the thread if it is `Paused`.
-                */
+                /// `Start` will start the Thread loop if it is not already running.
+                /// It will also Resume the thread if it is `Paused`.
                 virtual void Start() = 0;
 
                 /// `Pause` will pause the Thread loop if it is running.
@@ -68,6 +65,7 @@ namespace ESPressio {
                 virtual bool GetStartOnInitialize() = 0;
 
             // Utility Getters
+
                 bool IsRunning() { return GetThreadState() == ThreadState::Running; }
 
                 bool IsPaused() { return GetThreadState() == ThreadState::Paused; }
@@ -76,7 +74,25 @@ namespace ESPressio {
 
                 bool IsTerminated() { return GetThreadState() == ThreadState::Terminated; }
 
+            // Callback Getters
+
+                /// `GetOnInitialized` returns the callback to be invoked when the Thread is initialized.
+                virtual std::function<void(IThread*)> GetOnInitialized() = 0;
+
+                /// `GetOnStarted` returns the callback to be invoked when the Thread is started.
+                virtual std::function<void(IThread*)> GetOnStarted() = 0;
+
+                /// `GetOnPaused` returns the callback to be invoked when the Thread is paused.
+                virtual std::function<void(IThread*)> GetOnPaused() = 0;
+
+                /// `GetOnTerminated` returns the callback to be invoked when the Thread is terminated.
+                virtual std::function<void(IThread*)> GetOnTerminated() = 0;
+
+                /// `GetOnDestroying` returns the callback to be invoked when the Thread is being destroyed.
+                virtual std::function<void(IThread*)> GetOnDestroying() = 0;
+
             // Setters
+
                 /// `SetCoreID` sets the ID of the Core the Thread should run on.
                 virtual void SetCoreID(BaseType_t value) = 0;
 
@@ -88,6 +104,28 @@ namespace ESPressio {
 
                 /// `SetFreeOnTerminate` defines whether this Thread should be freed from memory when it is terminated. 
                 virtual void SetFreeOnTerminate(bool value) = 0;
+
+            // Callback Setters
+
+                /// `SetOnInitialized` sets the callback to be invoked when the Thread is initialized.
+                /// The callback function takes `IThread*` and ideally named `sender`.
+                virtual void SetOnInitialized(std::function<void(IThread*)>) = 0;
+
+                /// `SetOnStarted` sets the callback to be invoked when the Thread is started.
+                /// The callback function takes `IThread*` and ideally named `sender`.
+                virtual void SetOnStarted(std::function<void(IThread*)>) = 0;
+
+                /// `SetOnPaused` sets the callback to be invoked when the Thread is paused.
+                /// The callback function takes `IThread*` and ideally named `sender`.
+                virtual void SetOnPaused(std::function<void(IThread*)>) = 0;
+
+                /// `SetOnTerminated` sets the callback to be invoked when the Thread is terminated.
+                /// The callback function takes `IThread*` and ideally named `sender`.
+                virtual void SetOnTerminated(std::function<void(IThread*)>) = 0;
+
+                /// `SetOnDestroying` sets the callback to be invoked when the Thread is being destroyed.
+                /// The callback function takes `IThread*` and ideally named `sender`.
+                virtual void SetOnDestroying(std::function<void(IThread*)>) = 0;
         };
 
     }

src/ESPressio_Thread.cpp

@@ -14,6 +14,7 @@ namespace ESPressio {
         }
 
         Thread::~Thread() {
+            if (_onDestroy != nullptr) { _onDestroy(this); }
             SetThreadState(ThreadState::Destroyed);
             ThreadManager::GetInstance()->RemoveThread(this);
             if (_taskHandle != nullptr) { vTaskDelete(_taskHandle); }
@@ -22,6 +23,7 @@ namespace ESPressio {
         // Define the Terminate method of `Thread` here
         void Thread::Terminate() {
             SetThreadState(ThreadState::Terminated);
+            if (_onTerminate != nullptr) { _onTerminate(this); }
             if (GetFreeOnTerminate()) { ThreadGarbageCollector::GetInstance()->CleanUp(); } // Automatically trigger the Garbage Collector
         }
 

src/ESPressio_Thread.hpp

@@ -1,5 +1,7 @@
 #pragma once
 
+#include <functional>
+
 #include "ESPressio_IThread.hpp"
 #include "ESPressio_ThreadSafe.hpp"
 
@@ -20,6 +22,11 @@ namespace ESPressio {
         */
         class Thread : public IThread {
             private:
+            // Type Definitions
+                
+                /// `TOnThreadEvent` is a function type that can be used to handle Thread events.
+                using TOnThreadEvent = std::function<void(IThread*)>;
+
             // Members
                 uint8_t _threadID; // This is idempotent so doesn't need a `Mutex` wrapper.
                 ReadWriteMutex<ThreadState> _threadState = ReadWriteMutex<ThreadState>(ThreadState::Uninitialized);
@@ -29,6 +36,12 @@ namespace ESPressio {
                 ReadWriteMutex<uint32_t> _stackSize = ReadWriteMutex<uint32_t>(ESPRESSIO_THREAD_DEFAULT_STACK_SIZE);
                 ReadWriteMutex<UBaseType_t> _priority = ReadWriteMutex<UBaseType_t>(2);
                 ReadWriteMutex<BaseType_t> _coreID = ReadWriteMutex<BaseType_t>(0);
+            // Callbacks
+                TOnThreadEvent _onInitialize = nullptr;
+                TOnThreadEvent _onStarte = nullptr;
+                TOnThreadEvent _onPause = nullptr;
+                TOnThreadEvent _onTerminate = nullptr;
+                TOnThreadEvent _onDestroy = nullptr;
 
             // Methods
                 void _loop() {
@@ -69,6 +82,8 @@ namespace ESPressio {
                     _threadState.Set(state);
                 }
             public:
+
+
             // Constructor/Destructor
                 Thread();
 
@@ -104,6 +119,7 @@ namespace ESPressio {
                         return;
                     }
                     SetThreadState(GetStartOnInitialize() ? ThreadState::Running : ThreadState::Initialized);
+                    if (_onInitialize != nullptr) { _onInitialize(this); }
                 }
 
                 void Terminate();
@@ -113,10 +129,12 @@ namespace ESPressio {
                         Initialize();
                     }
                     SetThreadState(ThreadState::Running);
+                    if (_onStarte != nullptr) { _onStarte(this); }
                 }
 
                 void Pause() {
                     SetThreadState(ThreadState::Paused);
+                    if (_onPause != nullptr) { _onPause(this); }
                 }
 
             // Getters
@@ -149,6 +167,28 @@ namespace ESPressio {
                     return _startOnInitialize.Get();
                 }
 
+            // Callback Getters
+
+                std::function<void(IThread*)> GetOnInitialized() {
+                    return _onInitialize;
+                }
+
+                std::function<void(IThread*)> GetOnStarted() {
+                    return _onStarte;
+                }
+
+                std::function<void(IThread*)> GetOnPaused() {
+                    return _onPause;
+                }
+
+                std::function<void(IThread*)> GetOnTerminated() {
+                    return _onTerminate;
+                }
+
+                std::function<void(IThread*)> GetOnDestroying() {
+                    return _onDestroy;
+                }
+
             // Setters
 
                 void SetCoreID(BaseType_t value) {
@@ -170,6 +210,28 @@ namespace ESPressio {
                 void SetStartOnInitialize(bool value) {
                     _startOnInitialize.Set(value);
                 }
+
+            // Callback Setters
+
+                void SetOnInitialized(std::function<void(IThread*)> value) {
+                    _onInitialize = value;
+                }
+
+                void SetOnStarted(std::function<void(IThread*)> value) {
+                    _onStarte = value;
+                }
+
+                void SetOnPaused(std::function<void(IThread*)> value) {
+                    _onPause = value;
+                }
+
+                void SetOnTerminated(std::function<void(IThread*)> value) {
+                    _onTerminate = value;
+                }
+
+                void SetOnDestroying(std::function<void(IThread*)> value) {
+                    _onDestroy = value;
+                }
         };
 
     }