#25 add support for acquiring the currently running task and reentrant locking

Author: dave

examples/reentrantLocking/reentrantLocking.ino

@@ -0,0 +1,50 @@
+
+#include <TaskManagerIO.h>
+#include <ReentrantYieldingLock.h>
+
+// this is the global lock that can only be
+ReentrantYieldingLock myLock;
+volatile int myVar = 0;
+
+void log(const char* str, int val) {
+    Serial.print(millis());
+    Serial.print(' ');
+    Serial.println(str);
+}
+
+void nestedFunction() {
+    TaskMgrLock locker(myLock);
+    log("in nested function", myVar);
+}
+
+void setup() {
+    Serial.begin(115200);
+
+    taskManager.scheduleFixedRate(1000, [] {
+        TaskMgrLock locker(myLock);
+        log("start task function", myVar);
+
+        // the nested function will lock again, which is fine because it's in the same task
+        nestedFunction();
+
+        // now we release taskmanager to run other tasks, the will not be able to take our lock
+        taskManager.yieldForMicros(millisToMicros(500));
+
+        // now we have the context back lock again
+        nestedFunction();
+        log("exit task function", myVar);
+    });
+
+    taskManager.scheduleFixedRate(5, [] {
+        // here we have another task that locks, it will need to acquire the lock exclusively before entering
+        TaskMgrLock locker(myLock);
+        // do something that's unlikely to be optimised out, to waste some time
+        for(int i=0; i < 100; i++) {
+            myVar++;
+        }
+    });
+}
+
+void loop() {
+    taskManager.runLoop();
+}

src/ReentrantYieldingLock.cpp

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2018-present https://www.thecoderscorner.com (Nutricherry LTD).
+ * This product is licensed under an Apache license, see the LICENSE file in the top-level directory.
+ */
+
+#include "ReentrantYieldingLock.h"
+
+bool ReentrantYieldingLock::spinLock(unsigned long micros) {
+    // if our task already owns the lock then we are good.
+    if(locked && initiatingTask && taskManager.getRunningTask() == initiatingTask) return true;
+
+    // otherwise we contend to get the lock in a spin wait until we exhaust the micros provided.
+    bool areWeLocked = false;
+    while(!locked && micros > 50) {
+        areWeLocked = tm_internal::atomicSwapBool(&locked, false, true);
+        if (areWeLocked) {
+            ++count;
+            tm_internal::atomicWritePtr(&initiatingTask, taskManager.getRunningTask());
+            return true;
+        }
+        else {
+            taskManager.yieldForMicros(50);
+        }
+        micros -= 50;
+    }
+    return false;
+}
+
+void ReentrantYieldingLock::unlock() {
+    if(count != 0) {
+        --count;
+        return;
+    }
+    else {
+        tm_internal::atomicWritePtr(&initiatingTask, nullptr);
+        tm_internal::atomicWriteBool(&locked, false);
+    }
+}

src/ReentrantYieldingLock.h

@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2018-present https://www.thecoderscorner.com (Nutricherry LTD).
+ * This product is licensed under an Apache license, see the LICENSE file in the top-level directory.
+ */
+
+#ifndef TASKMANAGERIO_RENTRANTYIELDINGLOCK_H
+#define TASKMANAGERIO_RENTRANTYIELDINGLOCK_H
+
+#include "TaskManagerIO.h"
+
+/**
+ * A lock that is intended only for use within tasks, if the lock is taken it will allow task manager to run using
+ * it's yield for micros call until the lock becomes free. It is a spin lock, so it is safe to use with task manager.
+ * Unless you want to use the spin behaviour in a specific way, prefer using with TaskSafeLock
+ */
+class ReentrantYieldingLock {
+private:
+    tm_internal::TimerTaskAtomicPtr initiatingTask;
+    tm_internal::TmAtomicBool locked;
+    volatile uint8_t count;
+
+public:
+    /**
+     * Construct a reentrant yielding lock that is designed for use within task manager tasks
+     */
+    ReentrantYieldingLock() {
+        initiatingTask = nullptr;
+        locked = false;
+        count = 0;
+    }
+
+    /**
+     * Take the lock waiting the longest possible time for it to become available.
+     */
+    void lock() {
+        spinLock(0xFFFFFFFFUL);
+    }
+
+    /**
+     * Attempt to take the lock using a spin wait, it only returns true if the lock was taken.
+     * @param micros micros to wait
+     * @return true if the lock was taken, otherwise false
+     */
+    bool spinLock(unsigned long micros);
+
+    /**
+     * Release the lock taken by spinlock or lock. DOES NOT check that the callee is correct so use carefully.
+     */
+    void unlock();
+
+    uint8_t getLockCount() const { return count; }
+
+    bool isLocked() const { return locked; }
+};
+
+/**
+ * A wrapper around the task manager locking facilities that allow you to lock within a block of code by putting
+ * an instance on the stack, for example:
+ *
+ * ```
+ * ReentrantYieldingLock myLock;
+ * void myFunctionToLock() {
+ *     TaskSafeLock(myLock);
+ *     // do some work that needs the lock here. lock will always be released.
+ * }
+ * ```
+ */
+class TaskMgrLock {
+private:
+    ReentrantYieldingLock& lock;
+
+public:
+    TaskMgrLock(ReentrantYieldingLock& theLock) : lock(theLock) {
+        lock.lock();
+    }
+
+    ~TaskMgrLock() {
+        lock.unlock();
+    }
+};
+
+#endif //TASKMANAGERIO_RENTRANTYIELDINGLOCK_H

src/TaskManagerIO.cpp

@@ -53,6 +53,7 @@ TaskManager::TaskManager() : taskBlocks {} {
 	lastInterruptTrigger = 0;
 	taskBlocks[0] = new TaskBlock(0);
 	numberOfBlocks = 1;
+	runningTask = nullptr;
 	tm_internal::atomicWriteBool(&memLockerFlag, false);
 }
 
@@ -168,10 +169,12 @@ void TaskManager::cancelTask(taskid_t taskId) {
 void TaskManager::yieldForMicros(uint32_t microsToWait) {
 	yield();
 
+	auto* prevTask = runningTask;
 	unsigned long microsStart = micros();
 	do {
         runLoop();
 	} while((micros() - microsStart) < microsToWait);
+	tm_internal::atomicWritePtr(&runningTask, prevTask);
 }
 
 void TaskManager::dealWithInterrupt() {
@@ -180,9 +183,11 @@ void TaskManager::dealWithInterrupt() {
 
     auto lastSlot = taskBlocks[numberOfBlocks - 1]->lastSlot() + 1;
     for(taskid_t i=0; i<lastSlot; i++) {
-        auto task = getTask(i);
+        auto* task = getTask(i);
         if(task->isInUse() && task->isEvent()) {
+            tm_internal::atomicWritePtr(&runningTask, task);
             task->processEvent();
+            tm_internal::atomicWritePtr(&runningTask, nullptr);
             removeFromQueue(task);
             if(task->isRepeating()) {
                 putItemIntoQueue(task);
@@ -214,7 +219,9 @@ void TaskManager::runLoop() {
         // by here we know that the task is in use. If it's in use nothing will touch it until it's marked as
         // available. We can do this part without a lock, knowing that we are the only thing that will touch
         // the task. We further know that all non-immutable fields on TimerTask are volatile.
+        tm_internal::atomicWritePtr(&runningTask, tm);
         tm->execute();
+        tm_internal::atomicWritePtr(&runningTask, nullptr);
         removeFromQueue(tm);
         if(tm->isRepeating()) {
             putItemIntoQueue(tm);

src/TaskManagerIO.h

@@ -98,6 +98,7 @@ class TaskManager {
     volatile InterruptFn interruptCallback;
 
     tm_internal::TmAtomicBool memLockerFlag;      // memory and list operations are locked by this flag using the TmSpinLocker
+    tm_internal::TimerTaskAtomicPtr runningTask;
 public:
     /**
      * On all platforms there is a default instance of TaskManager called taskManager. You can create other instances
@@ -279,6 +280,15 @@ class TaskManager {
         if(maybeTask == nullptr) return 600 * 1000000U; // wait for 10 minutes if there's nothing to do
         else return maybeTask->microsFromNow();
     }
+
+    /**
+     * Gets the currently running task, this is only useful for places where re-entrant checking is needed to ensure
+     * the same task is taking the lock again for example. Never change the task state in this call, and also never
+     * store this pointer.
+     * @return a temporary pointer to the running task that lasts as long as it is running.
+     */
+    tm_internal::TimerTaskAtomicPtr getRunningTask() { return runningTask; }
+
 private:
     /**
      * Finds and allocates the next free task, once this returns a task will either have been allocated, making task