Initial Commit

Author: LK-Simon

.gitignore

@@ -396,3 +396,9 @@ FodyWeavers.xsd
 
 # JetBrains Rider
 *.sln.iml
+
+# Mac
+.DS_Store
+
+# VisualStudioCode
+.vscode

CMakeLists.txt

@@ -0,0 +1,12 @@
+set(COMPONENT_SRCDIRS
+    "src"
+)
+
+set(COMPONENT_ADD_INCLUDEDIRS
+    "src"
+)
+
+register_component()
+
+target_compile_definitions(${COMPONENT_TARGET} PUBLIC -DESP32)
+target_compile_options(${COMPONENT_TARGET} PRIVATE -fno-rtti)

README.md

@@ -1,2 +1,4 @@
 # ESPressio-Threads
-Threading Components of the ESPressio Development Platform
+Threading Components of the Flowduino ESPressio Development Platform
+
+

component.mk

@@ -0,0 +1,8 @@
+COMPONENT_ADD_INCLUDEDIRS := include
+COMPONENT_SRCDIRS := src
+CXXFLAGS += -fno-rtti
+CXXFLAGS += -DESPRESSIO_THREADS
+CXXFLAGS += -DESPRESSO_THREADS_VERSION_MAJOR=0
+CXXFLAGS += -DESPRESSO_THREADS_VERSION_MINOR=0
+CXXFLAGS += -DESPRESSO_THREADS_VERSION_PATCH=1
+CXXFLAGS += -DESPRESSO_THREADS_VERSION_STRING=\"0.0.1\"

examples/SimpleForeverThread/SimpleForeverThread.ino

@@ -0,0 +1,5 @@
+/*
+    An extremely simple example of an ESPressio Thread loop that runs on either core of the ESP32.
+*/
+
+#include <Arduino.h>

library.json

@@ -0,0 +1,18 @@
+{
+    "name": "Flowduino ESPressio-Threads",
+    "description": "Threding Library intended for use with multi-core ESP microcontrollers",
+    "keywords": "thread,threads,threading,esp,esp32,esp8266,espressif,multi-threading,multi-core",
+    "authors": {
+        "name": "Flowduino",
+        "maintainer": true
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Flowduino/ESPressio-Threads.git"
+    },
+    "version": "0.0.1",
+    "license": "Apache-2.0",
+    "frameworks": "arduino",
+    "platforms": "espressif32,espressif8266",
+    "dependencies": []
+}

library.properties

@@ -0,0 +1,9 @@
+name=Flowduino ESPressio-Threads
+version=0.0.1
+author=Simon J. Stuart
+maintainer=Flowduino.com
+sentence=Threding Library intended for use with multi-core ESP microcontrollers
+paragraph=This library is intended to be used with the ESP32 and ESP32-S2 microcontrollers. It is designed to allow the user to very easily create and manage threads on the microcontroller. This library is intended to be used with PlatformIO and the Arduino framework.
+category=Threading
+url=https://github.com/Flowduino/ESPressio-Threads
+architectures=esp32, esp32s2

src/ESPressio_IThread.hpp

@@ -0,0 +1,91 @@
+#pragma once
+
+// #define CORE_THREADING_DEBUG // Uncomment this to explicitly enable debugging for the threading module
+#include <Arduino.h>
+#include <cstdint>
+
+namespace ESPressio {
+
+    enum ThreadState {
+        Uninitialized,
+        Initialized,
+        Running,
+        Paused,
+        Terminating,
+        Terminated,
+        Destroyed
+    };
+
+    /*
+        `IThread` is a common Interface for all Thread Types provided by this library.
+        You can use it to reference any Thread Type without knowing the actual type.
+    */
+    class IThread {
+        public:
+        // Methods
+
+            /// `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!
+            */
+            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`.
+            */
+            virtual void Start() = 0;
+
+            /// `Pause` will pause the Thread loop if it is running.
+            virtual void Pause() = 0;
+
+        // Getters
+
+            /// `GetCoreID` returns the ID of the Core the Thread is running on.
+            virtual BaseType_t GetCoreID() = 0;
+
+            /// `GetStackSize` returns the size of the Stack the Thread is using.
+            virtual uint32_t GetStackSize() = 0;
+
+            /// `GetPriority` returns the priority of the Thread.
+            virtual UBaseType_t GetPriority() = 0;
+
+            /// `GetThreadID` returns the unique ID of the Thread.
+            virtual uint8_t GetThreadID() = 0;
+
+            /// `GetThreadState` returns the current state of the Thread.
+            virtual ThreadState GetThreadState() = 0;
+
+            /// `GetFreeOnTerminate` returns whether this Thread should be freed from memory when it is terminated.
+            virtual bool GetFreeOnTerminate() = 0;
+
+            /// `GetStartOnInitialize` returns whether this Thread should start running when it is initialized.
+            virtual bool GetStartOnInitialize() = 0;
+
+        // Utility Getters
+            bool IsRunning() { return GetThreadState() == ThreadState::Running; }
+
+            bool IsPaused() { return GetThreadState() == ThreadState::Paused; }
+
+            bool IsTerminating() { return GetThreadState() == ThreadState::Terminating; }
+
+            bool IsTerminated() { return GetThreadState() == ThreadState::Terminated; }
+
+        // Setters
+            /// `SetCoreID` sets the ID of the Core the Thread should run on.
+            virtual void SetCoreID(BaseType_t value) = 0;
+
+            /// `SetStackSize` sets the size of the Stack the Thread should use.
+            virtual void SetStackSize(uint32_t value) = 0;
+
+            /// `SetPriority` sets the priority of the Thread.
+            virtual void SetPriority(UBaseType_t value) = 0;
+
+            /// `SetFreeOnTerminate` defines whether this Thread should be freed from memory when it is terminated. 
+            virtual void SetFreeOnTerminate(bool value) = 0;
+    };
+
+}

src/ESPressio_Thread.cpp

@@ -0,0 +1,26 @@
+#include "ESPressio_Thread.hpp"
+#include "ESPressio_ThreadManager.hpp"
+
+#include "ESPressio_ThreadGarbageCollector.hpp"
+
+namespace ESPressio {
+
+    // Define the Constructor and Destructor of `Thread` here
+    Thread::Thread() : _threadID(0) {
+        _threadID = ThreadManager::GetInstance()->GetThreadCount();
+        SetCoreID(ThreadManager::GetInstance()->AddThread(this));
+    }
+
+    Thread::~Thread() {
+        SetThreadState(ThreadState::Destroyed);
+        ThreadManager::GetInstance()->RemoveThread(this);
+        if (_taskHandle != nullptr) { vTaskDelete(_taskHandle); }
+    }
+
+    // Define the Terminate method of `Thread` here
+    void Thread::Terminate() {
+        SetThreadState(ThreadState::Terminated);
+        if (GetFreeOnTerminate()) { ThreadGarbageCollector::GetInstance()->CleanUp(); } // Automatically trigger the Garbage Collector
+    }
+
+}

src/ESPressio_Thread.hpp

@@ -0,0 +1,165 @@
+#pragma once
+
+#include "ESPressio_IThread.hpp"
+#include "ThreadSafe.hpp"
+
+namespace ESPressio {
+
+    // Forward Declaration for `ThreadGarbageCollector`
+    class ThreadGarbageCollector;
+
+    /*
+        `Thread` is a class that represents a "standard" Thread in the system.
+        It is a wrapper around the system's Thread API, designed to make them much easier to use.
+    */
+    class Thread : public IThread {
+        private:
+        // Members
+            uint8_t _threadID; // This is idempotent so doesn't need a `Mutex` wrapper.
+            ReadWriteMutex<ThreadState> _threadState = ReadWriteMutex<ThreadState>(ThreadState::Uninitialized);
+            ReadWriteMutex<bool> _freeOnTerminate = ReadWriteMutex<bool>(false);
+            ReadWriteMutex<bool> _startOnInitialize = ReadWriteMutex<bool>(true);
+            TaskHandle_t _taskHandle = nullptr; // SHOULD be Atomic!
+            ReadWriteMutex<uint32_t> _stackSize = ReadWriteMutex<uint32_t>(10000);
+            ReadWriteMutex<UBaseType_t> _priority = ReadWriteMutex<UBaseType_t>(2);
+            ReadWriteMutex<BaseType_t> _coreID = ReadWriteMutex<BaseType_t>(0);
+
+        // Methods
+            void _loop() {
+                for (;;) {
+                    switch (_threadState.Get()) {
+                        case ThreadState::Paused:
+                        case ThreadState::Initialized:
+                        case ThreadState::Uninitialized:
+                            delay(1);
+                            break;
+                        case ThreadState::Running:
+                            OnLoop();
+                            break;
+                        case ThreadState::Terminating:
+                            SetThreadState(ThreadState::Terminated);
+                        case ThreadState::Terminated:
+                            if (_taskHandle != nullptr) { vTaskDelete(_taskHandle); }
+                            return;
+                    }
+                }
+            }
+        protected:
+        // Methods
+
+            /// Override `OnLoop` to provide the main loop for the Thread.
+            virtual void OnLoop() {}
+
+            /// Override `OnInitialization` to perform any setup required for the Thread before the Loop begins.
+            virtual void OnInitialization() {}
+
+        // Getters (Internal)
+
+        
+
+        // Setters (Internal)
+            
+            void SetThreadState(ThreadState state) {
+                _threadState.Set(state);
+            }
+        public:
+        // Constructor/Destructor
+            Thread();
+
+            ~Thread();
+
+        // Methods
+            void Initialize() {
+                if (_taskHandle != nullptr) { vTaskDelete(_taskHandle); } // Delete any existing task handle if it's there!
+                // Convert value of GetThreadID() to const char* for xTaskCreatePinnedToCore
+                char threadIDStr[3];
+                itoa(GetThreadID(), threadIDStr, 10);
+                
+                xTaskCreatePinnedToCore(
+                    [](void* parameter) {
+                        Thread* instance = static_cast<Thread*>(parameter);
+                        instance->_loop();
+                    },
+                    threadIDStr,                /* Name of the task. */
+                    GetStackSize(),                   /* Stack size of the task. */
+                    this,                    /* Parameter of the task (class instance). */
+                    GetPriority(),                       /* Priority of the task. */
+                    &_taskHandle,            /* Task handle to keep track of the created task. */
+                    GetCoreID()              /* Pin task to core 0. */
+                );
+                OnInitialization(); // Invoke any custom initialization behaviour before we change the state of the Thread
+                // Check if the state was changed to Terminating or Terminate during the OnInitialization() method
+                if (GetThreadState() == ThreadState::Terminating || GetThreadState() == ThreadState::Terminated) {
+                    vTaskDelete(_taskHandle);
+                    return;
+                }
+                SetThreadState(GetStartOnInitialize() ? ThreadState::Running : ThreadState::Initialized);
+            }
+
+            void Terminate();
+
+            void Start() {
+                if (GetThreadState() == ThreadState::Terminated) {
+                    Initialize();
+                }
+                SetThreadState(ThreadState::Running);
+            }
+
+            void Pause() {
+                SetThreadState(ThreadState::Paused);
+            }
+
+        // Getters
+
+            BaseType_t GetCoreID() {
+                return _coreID.Get();
+            }
+
+            uint32_t GetStackSize() {
+                return _stackSize.Get();
+            }
+
+            UBaseType_t GetPriority() {
+                return _priority.Get();
+            }
+
+            uint8_t GetThreadID() {
+                return _threadID;
+            }
+
+            ThreadState GetThreadState() {
+                return _threadState.Get();
+            }
+
+            bool GetFreeOnTerminate() {
+                return _freeOnTerminate.Get();
+            }
+
+            bool GetStartOnInitialize() {
+                return _startOnInitialize.Get();
+            }
+
+        // Setters
+
+            void SetCoreID(BaseType_t value) {
+                _coreID.Set(value);
+            }
+
+            void SetStackSize(uint32_t value) {
+                _stackSize.Set(value);
+            }
+
+            void SetPriority(UBaseType_t value) {
+                _priority.Set(value);
+            }
+
+            void SetFreeOnTerminate(bool value) {
+                _freeOnTerminate.Set(value);
+            }
+
+            void SetStartOnInitialize(bool value) {
+                _startOnInitialize.Set(value);
+            }
+    };
+    
+}