TaskManagerIO documentation: scheduling, yielding, stack, signalling

[hattesen]

TaskManagerIO (and IoAbstraction) look like very useful abstraction layers that allows easy portability of applications, hardware changes and portability to new platforms, while assisting in producing more declarative code.

However, I have been unable to find any documentation that explains a number of implementation details and recommended usage of TaskManagerIO:

Scheduling

How does TaskManagerIO scheduling work?

• How is the list of tasks organized
• Scheduling fairness/starvation (rouns-robin?)
• How a long-running task can (and should) ensure to relinguish control at regular intervals, and which methods are available for that, e.g.
  • yield() - declared weak in Arduino core
  • delay(millis) - declared in Arduino core, calls yield() if millis>=1
  • yieldForMicros(micros) (the only one documented)

Low Power (Sleep) Support

Does TaskManagerIO support entering low power sleep (hardware) modes, if no tasks are scheduled to run for a number of milliseconds?

Signalling, Events, Semaphores, Messages

Documenting inter-task signalling, events, semaphores, messaging: how to create/obtain and how a task tells the scheduler to suspend execution until a resource is available, possibly using a lambda: waitFor(lambda, timeoutMillis)

Execution Stack

Documenting how stacks and execution contexts are allocated and maintained across tasks.

[davetcc]

I'll try and answer a few of them here for now, with the aim to get them into documentation over time. I'll start with the easy answers and work through the others as I have time.

Scheduling fairness/starvation (rouns-robin?)

It is an unfair scheduler, a work queue ordered by time, nearest time wins always. If you've used Java before consider this somewhat like ScheduledExecutorService or if you're accustomed to Javascript somewhat like setTimeout(..)

How a long-running task can (and should) ensure to relinguish control at regular intervals, and which methods are available for that, e.g.

In such a task use taskManager.yieldForMicros(..) this is the only way to give control back to task manager.

Low Power (Sleep) Support

It is very easy to implement whatever low power modes your board supports, there's even an example in the documentation for SAMD: https://www.thecoderscorner.com/products/arduino-libraries/taskmanager-io/task-manager-low-power-samd-example/

You just effectively add a couple of lines to the main run loop to check how long to the next task, and if the threshold for sleeping is met, then do so.

[davetcc]

Signalling, Events, Semaphores, Messages

Task manager is designed really to block as little as possible, it is unfortunate though that many embedded APIs are synchronous and make this harder.

At the moment the best way to handle external signals is to use an event, see the events section of: https://www.thecoderscorner.com/products/arduino-libraries/taskmanager-io/

There is also SCCircularBuffer built into SimpleCollections, you can use this like a queue of work, and have an event that takes work from the buffer. IE an above mentioned event would contain a circular buffer, and it would trigger whenever there was work in the queue. See the examples in SimpleCollections library for that.

If you need a native critical section or mutex, be very careful using that in task-manager that it does not lock the task thread completely. Task Manager tasks run on a single-thread (but scheduling. event triggering, and submitting is thread-safe). The idea is, that you can push longer-running work away from taskmanager in an RTOS environment, IE create other threads with a circular buffer or other taskManager instance that acts like a queue.

[hattesen]

Thank you very much for the information!

Does TaskManagerIO intercept calls to the Arduino Core yield() method (overriding the weak definition) so existing Arduino code/libraries that calls yield() and delay() automatically will become well behaved cooperative tasks when run in TaskManagerIO and give other tasks run time?

[davetcc]

No, by default it doesn't do that, there are a few reasons for that.

We tried it for a while in the early days and decided it was best not to do it. Here's just a few of the reasons we ran into:

• On ESP8266 and possibly ESP32 it could trigger the watchdog.
• If you're using it with FreeRTOS or mbed (and a lot of people including me do), taking over yield could lead to very unpredicable behaviour.
• TaskManagerIO operates all tasks on a single thread of execution, (I guess in the yield call you could check if the thread was correct first). There are helper methods for this in the library, but they may need extending for additional cases for this.
• If task manager is part of larger system, hooking into yield would cause major issues.

There's nothing to stop anyone from doing it, if they know that it would not have unpredictable results, but it is not a good default option. What I'll do is I'll wrap the embedded yield() call that's in yieldForMicros behind a compiler flag so anyone wanting to this could avoid a recursive call, then anyone wanting to map yield to yieldForMicros could do if they thoroughly evaluated that it could never be called on the wrong thread etc.

[davetcc]

Many people when they first see task manager think that it is akin to FreeRTOS, but it is not. It is designed to co-exist nicely with FreeRTOS and provide a simplified solution for scheduling and events. Really, it was originally the core of tcMenu, but it was so useful that we broke it out.

[davetcc]

You can have two task managers for example, but each one would run on a single thread, you can submit work to a task manager from any thread, but it will always run on the task manager thread that it is submitted to.

[davetcc]

So in terms of storage arrangements, there are two possibilities, you set DEFAULT_TASK_BLOCKS to 1 and DEFAULT_TASK_SIZE to the maximum number of tasks ever needed. No allocation will take place outside of set up.

Otherwise, you can either rely on the defaults (large 32bit board is usually 16 blocks with 16 tasks each) and then one block will be allocated at start up. If another block is needed, it will be allocated, up until the maximum block is reached. Once allocated the memory is kept until the task manager is destructed. This gives an arrangement of tasks organized into blocks.

Each task has a next task pointer within it. For performance, task pointers are then arranged in a linked list by time order, this list signifies what runs next. It is fast for execution, slower for insertion. The only exclusion to that is events and interrupt handling. Where events can be triggered at any point by using myEventObj.markTriggeredAndNotify(). Interrupts are triggered by the raw ISR being called and then marshalling that through the task manager queue.

[davetcc]

Here's an example of what a task manager may look like at runtime, consider events as just special tasks basically.

TaskManager instance
    interrupt triggered [ true or false ]
    marshalledInterruptHandler (called on taskmanager thread)
    TaskBlock 1
         Task A 100 millis from now
         Task B 200 millis from now
         Empty Slot
         Task C 1000 millis from now
    TaskBlock 2
        Task D overdue
         Empty Slot
         Empty Slot
         Empty Slot

    Ordered Task Queue  (linked list of Task pointers)
        Task D
        Task A
        Task B
        Task C

[davetcc]

And lastly, the library is thread safe for insertion of tasks, cancellation and triggering from any thread. This is done using compare and swap where supported, or board provided atomics. If they are not available or on an unknown board it defaults to a reasonably safe operation on Arduino emulating CAS.

You must make sure any memory/data you access in tasks that cross threads is correctly visible. Ie memory fence around read write or CAS.

[davetcc]

I'll aim to get this lot into the documentation at some point, but at least for now, it's documented to some extent here.