Multitasking

[alranel]

👋 We would like to extend the Arduino API to support a long-wanted feature: multitasking.

🔍 The problem

Timing logic is one of the most common parts of every Arduino sketch: when you blink a LED or regulate the speed of a motor you’ll need pauses between signals; likewise, to detect button presses or read rotary encoders you’ll need multiple signal readings separated by pauses.

We all started with the well-known delay() function seen in the Blink example, being the simplest way to pause sketch execution between one command and another. However, as soon as you need to run two different things at the same time, with different timing needs, you’ll find out that this approach doesn’t work. Also, blocking the execution of your loop() will have side effects such as slow performance in user interaction and network operations.

After seeing the limitations of delay() we all learned about state machines, i.e. how to turn a sketch from blocking to non-blocking by using the millis() function (as seen in the BlinkWithoutDelay example).

Then, in order to make code more readable and support multiple state machines, they are usually moved into classes exposing an .update() method to be called in the loop. This approach is solid but if you’re a novice user and need multiple state machines things get suddenly quite complicated as you’re forced to learn about classes a bit too early in your learning journey.

State machines also come with drawbacks:

• They’re verbose. Even for a single task like blinking a LED where you would just like to say “blink, wait, blink again”, you need to use multiple variables, call a millis() function, do math and change the state variables.
• They make code difficult to read. Since code doesn’t visually follow the natural execution flow, it becomes hard to understand and debug.
• They always run in a single core. Even if state machines allow you to make your code non-blocking, thus letting your loop() run quickly, they all run in the main thread. This means you can’t leverage the capabilities of modern multi-core boards (such as Nano RP2040 Connect) which can truly run code in parallel.
• They are power-hungry. The concept of “busy loop” and the continuous polling required to update state machines doesn’t let your microcontroller rest even when it should just sit and wait for something to happen. For battery-powered projects, this is not nice.

💡 The solution!

The limitations of state machines can be overcome implementing multitasking, aka threads: you write a block of code that needs to be run in parallel, and let the operating system schedule it in the proper way so that it does not interfere with other tasks.

How does multitasking compare to state machines?

• Reduced verbosity. No more state variables and syntax glue.
• Better code readability. Code layout makes the flow more clear because each thread is a distinct code block.
• Multi-core support. Threads can be distributed among all available cores.
• Low-power compatibility. The mantra of state machines is non-blocking everywhere, and continuous polling. With multitasking, you can dedicate each thread to a specific task, bringing blocking paradigms back: for instance, when polling a button signal you can have delay(100) calls between one reading and the other, with no perceptible effect on user experience but significant power saving. Interrupts can be used too.

Now, we don’t have any official Arduino API for this. Multiple libraries exist, such as:

• Scheduler (SAM/SAMD only)
• ThreadedTimer (mbed)
• Arduino_FreeRTOS_Library and several others bringing the FreeRTOS API to AVR

Also, some cores expose native functionality:

• For RP2040 boards, the Pico SDK provides this functionality (see here)
• The unofficial Pico core for Arduino by Earle F. Philhower provides built-in setup1() and loop1() functions
• For boards supported by the Mbed Arduino core, rtos::Thread() is available too
• The ESP32 core exposes the vTaskDelay() API from FreeRTOS

None of these approaches are portable. Standardizing a higher level API would make life easier to users. Also, the lack of a portable API also limits the creation of libraries which might want to use threading.

📝 Requirements

How can we design a nice, simple, Arduinish API for multitasking?
Let’s try to lay down some general requirements:

1. Abstraction. The API shall be abstract enough that all platforms can implement it, regardless of their underlying RTOS, HAL or architecture.
2. Transparent support for any number of cores. A program written with the multitasking API shall work gracefully on single-core and multi-core boards without adaptation.
3. Compliance with Arduino API style. The API shall follow the Arduino API style.
4. Backwards compatibility. Implementation of multitasking API in a platform shall have no effects or limitations on traditional .ino single-core sketches, even if they use C++ constructs that are beyond the advertised Arduino API.

What more? Let’s discuss:

1. setup()/loop()? Shall we provide a setup()/loop() combo inside each additional thread?
2. Multiple files? Shall we enforce that each thread is implemented in a separate file?
3. Using threads from libraries? How do we allow the creation of libraries which create their own additional threads? For instance, a library that reads a matrix keyboard in a separate thread and can be called from the (all the) user’s threads to get the keypresses.
4. Using libraries from threads? What mechanisms should we provide to library developers to help them make their libraries thread-safe (even if they do not need multiple threads)?
5. Inter-thread communication? What mechanisms do we need to ease the communication between threads? Shall we provide shared variables (with concurrency protection)? Shall we provide channels/pipes? How can we block the execution of a thread until another thread sends data, to avoid continuous polling?
6. Shared serial communication? How do we expect users to use Serial.print() and Serial.read() in a concurrent way?
7. Thread-safe bus communication? How to read SPI and I2C from multiple threads?

🚀 Now what?

As a conversation starter, we developed a possible implementation, which is hosted in this repository:

👉 https://github.com/arduino-libraries/Arduino_Threads

It satisfies many of the requirements above, but not all of them. Please help us testing it! Comments are very welcome.

But this is just the beginning as there could be more ideas from the community so let’s get the discussion started! Please, possibly structure your comments according to the above requirement list, and feel free to post alternative design proposals.

[domschl]

Have a look at https://github.com/muwerk/muwerk
A cooperative scheduler that uses MQTT-like queues for communication.
There are extensions for network-handling and samples.

[rei-vilo]

I've explored multi-tasking against the Texas Instruments LaunchPad boards with the Galaxia Library designed for Energia.

Energia bring the Arduino IDE and SDK to the Texas Instruments LaunchPad boards. Energia MT stands for Energia Multi-Tasking.

The library relies on TI-RTOS and exposes the RTOS elements as objects.

• Threads elements include HardWare Interrupt (HWI) and Tasks.
• Synchronisation elements include Event, Semaphore, Mailbox and Clock.

Three major challenges:

1. Find a common set of function names for the different elements;
2. Provide documentation and examples for each thread and synchronisation element (as at Exploring RTOS with Galaxia on Energia MT);
3. Manage peripherals: I hadn't to deal with this challenge, as the peripherals are part of and managed by TI-RTOS; and
4. Build debugging tools.

Feel free to visit the Galaxia Library GitHub repository.

[aentinger]

Hi @domschl!

Thank you for bringing the muwerk project to our attention 👍. I've looked a bit around to determine which Arduino boards (or rather Arduino cores) would be supported but did not really find out. Maybe you consider updating your documentation concerning this.

The Arduino_Threads library, which is our first (but not final approach towards providing multitasking on Arduino, hence this discussion) is wrapping mbed-os multitasking primitives and therefore provides preemptive multi-tasking where one does not need to be concerned about handing back control to allow another task to run, much like @rei-vilo's Galaxia library seems to do.

In any case I invite the both of you (and everyone else) to go and take a look at Arduino_Threads and, if interesting, provide some feedback either via a opening of an issue or open/participate in the discussions.

Cheers, Alex

[domschl]

Hi @aentinger,

Arduino-core dependency is handled by muwerk's ustd library and it's platform defines. It's very highly portable, has no dependencies on any frameworks and can usually be adapted to a new framework by filling in a few defines, see: ustd_platform.h.

The design-considerations were:

• make it ultra-lightweight (the scheduler can run on attiny 8kb rom 512 ram(!))
• highly portable (no dependencies on OS-platforms for multi-tasking)
• use cooperative instead of preemptive multitasking and use async pub/sub communication between cooperative tasks, using MQTT's ideas locally. A task can be exactly the code that used to live in an Arduino loop. All existing Arduino libraries still work with no need to change.

Why those decisions?

1. Preemptive multitasking is not needed to 'untangle' the state-machine-of-doom mess. What's needed is a simple method to decompose:
2. To organically decompose the 'state-machine of doom': one can start to simply copy the existing code into one muwerk task.
3. Then one can successively take parts of the state-machine (e.g. handling of one sensor) out of the main code and put it into a separately scheduled task.
4. To glue those tasks together, pub/sub messages are used: the sensor tasks publishes the measured values, and another task can subscribe to those values.

Application-blocks that implement parts of a complete Arduino application are call mupplets (see https://github.com/muwerk, different projects). Mupplets are libs that start tasks to fulfil jobs (e.g. monitoring a sensor and publishing results), and those are highly composable.

Additionally, if a network enabled hardware is used, all internal communication can be transparently exposed via MQTT (e..g used to make sensors available in home-assistant with 3-4 lines of code...)

In short: task run cooperatively, because that vastly reduces complexity (no synchronization and locking needed, much easier to port), communication uses async pub/sub [which would allow to later-on use a preemptive multi-core kernel, without requiring software-changes(!)], communication can be extended via MQTT transparently on network-enabled hw. The whole design encourages thinking in loosely and asynchronously coupled blocks.

Since cooperative multitasking depends on every task to be well-behaved, we have a tool (mutop, see below) to check timing behaviour of each task.

[dsyleixa]

IMO cooperative MT makes no sense, preemptive MT like std::thread is required (as it is already available for ESP32-Arduino-API)

[drfuzzyness]

Another existing library of note is AceRoutine which can run coroutines all the way down on ATmega328P processors (Arduino Uno/Nano). It uses a variety of tricks to run entirely in software while being statically allocated.

I'd find it helpful if the common threading language implementation could have a "minimal" base that could be implemented by a library like AceRoutine to provide support for older and cheaper processors. That said, I understand that might not be possible given the design challenges behind implementing pseudo-threading on microcontrollers.

[gigaj0ule]

Oh boy, I’ve been doing multitasking in arduino for years already!

I use freertos and it works super well. Here is an example:

https://github.com/gigaj0ule/system42/blob/61ce1f59801d8833cc4effde6495451c2970af76/projects/demo/sketch.ino#L40

I’m sure it is possible to generalize free rtos so that it works on every MCU, and, if we want it to be user friendly, we can put wrapper functions around the API that are easier to understand by newcomers.

FreeRTOS just needs a systick, which arduino already has. When you call vTaskDelay() in a thread, the scheduler checks to see if any other threads should run and then goes and runs them.

[pnndra]

I guess you should have a look at the repository... Arduino has been running on top of a RTOS for a few years now so the issue was not having threads but rather make them accessible to non programmers. We developed a sort of virtual environment where you can run multiple sketches in parallel having them isolated and at the same time sharing peripherals and data without the need for explicit semaphores/mutexes... Please check out what we did and comment after evaluating it...

[rei-vilo]

Yes, hence the 4 recommendations I posted.

It seems the Segger programmers-debuggers don't support mbedOS (yet).

There is currently no plug-in for Mbed OS available, but you can create one yourself:
segger.com/products/debug-prob…r/thread-aware-debugging/

[pnndra]

@rei-vilo as i was writing above our intent is not to provide a RTOS API but rather to make multitasking as invisible as possible. you won't find on our implementation proposal semaphores or synchronization mechanisms because these are embedded in the object variables we use to exchange data between threads/sketches. the infrastructure is also designed to allow each sketch to use peripherals as they would normally but in the background there is a thread safe mechanism that arbitrates access, again making this seamless.
debugging tools are an important topic however the good thing is that again we're targeting our traditional users who mainly debug using serial and here as well we added the possibility to prefix the prints a sketch outputs with a thread name so that the output can easily be filtered

[rei-vilo]

Thank you for the clarification. I think this solution will appeal to the large base of Arduino users and fans!

[dsyleixa]

std::thread (downsized but quite C++14 std::thread compatible) is already available for ESP32-Arduino API (freeRTOS-based) and that's actally what I also expect as an Arduino_Threads implementation.

[torntrousers]

Would by super useful and love this approach with clear description and soliciting community input!

[pnndra]

glad to hear this. i hope to see feedback soon, either here or in https://github.com/arduino-libraries/Arduino_Threads/discussions

[EdwinFairchild]

interesting stuff. Imagine also an Arduino profiling library that adds hooks to those threads and then uses something like processing to display how your program is executing. Heck you could integrate it into the IDE that would be cool. While most RTOSs have their profiling features you usually need third-party complicated tools to view the output.

[aentinger]

This would be a great feature indeed. I'll be noting it down, maybe we can put a feature like this ("enhanced tooling support for debugging multitasking) into our development pipeline.

CC @per1234 @facchinm @alranel @pnndra

[domschl]

The muwerk cooperative scheduler (which can run unmodified Arduino code and libs) has such a tool mutop.

It can even be cascaded to connect a simple Arduino-Uno via serial and get multiple, simple concurrent loops on the uno with process monitoring: Arduino bridge monitoring. Source length: 70 lines for both ESP and Arduino.

[aentinger]

This was probably meant as a reply to @EdwinFairchild's comment. Really neat tool, it would be great if we could add something like this for Arduino_Threads too 🚀 !

[dsyleixa]

cooperative MT makes no sense, preemptive MT like std::thread is required (as already available for ESP32-Arduino-API)

[jerabaul29]

A meta / brainstorming comment.

Concurrency is hard, is there any way to help the user not to shoot themselves in the foot, both within multitasking per se, and when considering multitasking + interrupts which makes things even worse?

I was reading quite a bit around these questions in both the 'Embedded Rust book' and the 'RTIC' book. These, together with Rust in itself, go through great care to make sure that the user cannot shoot themselves in the foot too easily. It was an eye opener for me to see how much care must be taken to avoid UB. I guess in cpp there will be needs to be extra careful as soon as concurrency is taking place.

Also, as soon as there is multitasking, arises the question around for example priority of tasks and preemption; any thoughts on this (for example, the Arduino article below was not saying anything about these questions)?

Given the API examples provided at https://docs.arduino.cc/tutorials/generic/multiple-blinks?_gl=1*16o0z1b*_ga*OTQyNzM3MTcuMTY1OTYzNjcwNg..*_ga_NEXN8H46L5*MTY1OTcxMzk0NS4zLjEuMTY1OTcxNTcyMC42MA.. , if multitasking takes this kind of route in Arduino, I guess this would mean providing only quite primitive multitasking with quite coarse control, but also helping the user not shooting themselves in the foot by doing so?

[aentinger]

Hi @jerabaul29 ☕ 👋

Thank you very much for your input 🙇 ! We are fully aligned on the fact that multi-tasking is really hard!

In our Arduino_Threads library which, coincidentally has nothing to do with the Scheduler example you linked above, we are trying to prevent as much as foot-shooting as possible by providing pre-defined types allowing simple thread-safe data-exchange between multiple threads (even when running a preemptive scheduler, as we do). Currently there are two mechanisms for data exchanged in place, one we call the Shared abstraction and the other is called Source/Sink.

Some pre-eliminary documentation on those data exchange mechanisms can be found here. Right now, as the whole library is in a beta-state we are not sure if these approaches are the right ones, or if they can be improved, adapted, etc. Hence we are seeking the input of the community 🙇 !

We'd love to hear from you over there too!

[jerabaul29]

Aaah, thanks for the explanation! Yes, I think I am confused between the different alternatives you are working on at the moment. I arrived here from the Scheduler example, which is why I was confused about which solution you work on, sorry. Sounds good!

[aentinger]

Yeah, sorry 🙇 . We should have probably made that a bit clearer 😉. Scheduler is not in focus right now and only works for ArduinoCore-sam/samd supported boards. Arduino_Threads by comparison currently runs only on ArduinoCore-mbed enabled boards. Since all those boards supported by ArduinoCore-mbed have quite different underlying MCU platforms it could be quite an undertaking to retrofit them into Scheduler 😉 .

[rei-vilo]

Three questions:

• Some modern MCUs are multi-core: STM32H747, RP2040. How to attach one thread to a specific core?
• Does the Arduino Threads plan to feature events? This is an effective way for coordinating threads.
• In the Source/Sink case, when the producer thread adds a new value, could it raise an event at the consumer thread?

[aentinger]

Hi @rei-vilo ☕ 👋

Thank you for your questions and let's get into it:

Some modern MCUs are multi-core: STM32H747, RP2040. How to attach one thread to a specific core?

That's a question we've asked ourselves. While its true that both STM32H747 and RP2040 are multi-core by nature, the Arduino "build system" does currently not think of them that way. That is to say you can either compile a sketch for the M4 core of the H7 or for the M7 core of the H7 (although those two sketches can communicate via RPC). Right now you'd be building a multi-threaded sketch for each core (which would also clarify which thread it running where) and then facilitate communication via RPC. Not very beautiful, but doable. Seamless multi-core multitasking the way you describe it would definitely be a lot of work 😉 .

Does the Arduino Threads plan to feature events? This is an effective way for coordinating threads.

There is already some minimal API allowing event usage in place, but its purpose is mostly global thread synchronisation. Events would definitely be a sensible addition. What kind of use cases do you see? What kind of API would you wish for?

In the Source/Sink case, when the producer thread adds a new value, could it raise an event at the consumer thread?

This is already done within both Shared and Sink/Source. When any of those two transport mechanism is empty, that is to say that the last value stored inside has been consumed, then the next call to read will block (unless you use non-blocking Sink). When another thread stores data into any of those data exchange mechanism an event is sent (by the framework, no user interaction necessary) and the waiting thread becomes automagically unblocked (ready) and consumes the data.

Cheers, Alex

[dsyleixa]

as to synchronizing IMO events are not indispensable; one might use semaphores, mutexes or atomic variables as well, e.g. set in any thread or by common interrupts.

[dsyleixa]

IMO the best way would be to implement a (quite original) std::thread or even a pthread-like API syntax. Most of the Arduino-users targeting preemptive multithreading are most probably already used to pthread a/o std::thread on other platforms (e.g., Raspberry Pi), and to benefit from the experience and from standard C/C++ examples in the web the very intuitive pthread/std::thread syntax is useful, reasonable, and sensible also for common (not extremely high skilled) Arduino users.
OTOH, e.g. how ESP32 developers did their (other) pthread +std::thread thing is quite useful but it's not 100% compatible with standard C/C++ syntax, sometimes leading to confusion.

simple example for an ESP32 std::thread MT pattern:

// std::thread for ESP32, Arduino IDE

// thread loops can be exited by internal conditions (e.g. via break or return) 
// or all inner loops by setting THREADRUN=false at any location.

#include <Arduino.h>
#include <thread>
#include <freertos/task.h>
#include <esp_task.h>

volatile static bool THREADRUN = true;  // just for simplification; atomic <bool> of course would be a better alternative


//--------------------------------------------------------------------
void function2() {
   // vTaskPrioritySet( NULL, ESP_TASK_MAIN_PRIO ); // set Priority = main prio      // for optional settings
   Serial.println((String)"   function2 started"); 
   while(THREADRUN) {      
      // do stuff
   }
   Serial.println((String)"   function2 terminating"); 
}

//--------------------------------------------------------------------

void function1() {
   // vTaskPrioritySet( NULL, ESP_TASK_MAIN_PRIO ); // set Priority = main prio      // for optional settings   
   Serial.println((String)"   function1 started"); 
   while(THREADRUN) {      
      // do stuff
   }
   Serial.println((String)"   function1 terminating"); 
}

//--------------------------------------------------------------------

void function0() {
   // vTaskPrioritySet( NULL, ESP_TASK_MAIN_PRIO ); // set Priority = main prio      // for optional settings 
   Serial.println((String)"   function0 started"); 
   while(THREADRUN) {      
      // do stuff
   }
   Serial.println((String)"   function0 terminating"); 
}

//--------------------------------------------------------------------
//--------------------------------------------------------------------
void setup() {
   Serial.begin(115200);

   std::thread thread_0 (function0);
   std::thread thread_1 (function1);
   std::thread thread_2 (function2);
   
   Serial.println((String)"\n all threads being started, now waiting for all being terminated and to join main thread \n");  // <<<<<<  
   
   thread_0.join();
   thread_1.join();
   thread_2.join();
   
   Serial.println((String)"\n all threads joined, program terminated\n");  // <<<<<<  
}


//--------------------------------------------------------------------
void loop() { // empty placeholder for Arduino compatibility
   // when using repetitive code also in the standard loop() then this loop won't terminate after main/setup has finished
}

[aentinger]

Hi @dsyleixa ☕ 👋

Thank you very much for providing this input. I was not aware that ESP was providing some compatibility with std::thread and I will definitely look into this. Good stuff! You've got any experience with how to make std::thread available on devices without a complete libcstdxx?

Cheers, Alex

[dsyleixa]

Hi Alex,
Apart from my Raspberry Pi (2B, 3B), I only use std::thread MT for my ESP32, where I am using it very successfully for all sorts of projects. Regrettably my earlier requests for having preemptive MT also for ARM based boards (esp. DUE and M4) have been viewed with disapproval and discarded by the devs and collaboraters in the github Arduino repo so I dropped those boards. But gladly looking forward when now it will be given a new chance!

PS,
for the future also Raspberry Pico and other RP2040 boards from 3rd party manufacturers will surely benefit a lot from it!

[dsyleixa]

PPS,
as you will know, ESP32 is a dual core, but in the Arduino API you don't have to notice or pay attention to it at all: all threads are automatically assigned to one or the other core - but you can also perhaps do this arbitrarily, manually, too, which might be useful for special purposes and settings (e.g., special thread prio architectures, but I never needed to do it by myself though).

[aentinger]

It's good that you mention this 👍. For now Arduino_Threads only supports multi-threading on a single core although a couple of Arduino boards (i.e. Portenta H7 or Nano RP2040 Connect) have more than one core on-chip. The Portenta H7 even falls in the asymetric multiprocessor category, since it contains a M4 and a M7 which can be clocked at different speeds. I suppose any developer would like to have a little more control over on which core a thread would be assigned in this case. Your thoughts?

[dsyleixa]

tbh, IMO MT on all cores for multicore-boards is indispensible, just like ESP32-std::thread and C/POSIX pthread and C++14 std::thread do, and as to assigning cores manually it could be a precious feature too, as stated (e.g. for high-prio threads which must not block watchdog/system threads running on another core).

[dsyleixa]

another issue can be solved by std lib syntax easily too: thread-safe r/w communication when using std::mutex.
e.g., if 1 thread is accessing i2c or Serial() and another parallel thread requires access too, or if different threads read or write simultaneously to identical global variables or arrays, then simply the thread which came first may reserve access by mutexes, and when finished then simply frees it again: the timeslice scheduler will not muddle that up when switching to the other thread intermediately, and those threads cannnot access those resources until they have been unlocked again (provided they also use mutex protection).
A simple ESP32 std::thread/mutex example of how it's implemented there:

// std::thread plus mutex for ESP32, Arduino IDE

#include <Arduino.h>
#include <thread>
#include <freertos/task.h>
#include <mutex>


#ifndef LED_BUILTIN
#define LED_BUILTIN 13
#endif

using namespace std;

mutex  serial_mutex; // std::mutex 


void loop1() {
    thread_local uint32_t counter = 0, i=0;  
    vTaskPrioritySet(NULL,0); //set Priority
    
    while(true) 
        serial_mutex.lock();
        Serial.println((String)"this is loop1, counter="+counter);
        serial_mutex.unlock();
        counter++;
        // do stuff     
        delay(2);
    }
}

void loop2() {
    thread_local uint32_t counter = 0, i=0;  
    vTaskPrioritySet(NULL,0); //set Priority
    
    while(true) {
        serial_mutex.lock();
        Serial.println((String)"this is loop2, counter="+counter);
        serial_mutex.unlock();
        counter++;
        // do stuff     
        delay(2);     
    }
}



void setup() {
  Serial.begin(115200);
  delay(1000);
 
  thread  thread1(loop1);     // starting 1st std::thread
  thread  thread2(loop2);     // starting 2nd std::thread
}


void loop() {
    static uint32_t main_loop_counter = 0;
    serial_mutex.lock();
    Serial.println((String)"\nthis is main loop, main_loop_counter="+main_loop_counter );
    serial_mutex.unlock(); 
    main_loop_counter++;
    delay(100);
}

(edit, simplified)

[aentinger]

Thank you for taking the time describing this use-case. This is actually something that we already have considered and Arduino_Threads does provide thread-safe communication, i.e. thread-safe serial-writing would be done via the Serial.block()/.unblock() - API, for an example see here. In a similar way SPI and I2C (Wire) are made thread-safe by providing a single-function, thread-safe API like demonstrated here. A bit of theory on what happens in the background is documented here. Please let me know, what do you think of this approach?

[dsyleixa]

hi,
yes of course Serial.block/unblock might do as well although the standard approach via mutexes would be more common and more suitable for general purposes.
Additionally I would suggest lock/unlock instead of block/unblock (!)
I understand that Arduino often does not use standardized C/C++ lib syntax for reasons of simplicity (e.g., digitalRead/Write, analogRead/Write, delay). But std::thread / std::mutex are already very easy, handy, logical, suitable, and very common, so there's no need to invent another API syntax from scratch in my opinion, with only dubious (and falsely claimed) better usability or benefits.

[dsyleixa]

to summarize, IMO https://github.com/arduino-libraries/Arduino_Threads/blob/main/docs/threading-basics.md is the wrong approach. Instead, as I have shown by my examples above, std::thread is absolutely fine by design and performance and also absolutely suitable also for beginners.

[rogernolan]

I think there are two very different audiences for multithreading on Arduino. The difference between them is encapsulated in the Arduino API Style Guide with:

Assume you are writing an API for an intelligent person who has not programmed before

It's very true that the std::thread is an OK design and that it is battle proven. However I think as soon as you need something like std::mutex or let's go further, std::atomic_flag in a sketch you violate that part of the API Style Guide. I believe that a multithread API should be very simplified and opinionated in order to give those non-programmers the 20% functionality that gives 80% of the benefits of multi tasking - specifically and simply running multiple sketches in parallel - without the massive pain that lurks in the remaining parts of multitasking. I'd go so far as to implement it more like multiprocessing: no shared programatic state, hidden or automagic synchronisation primitives etc.

I think that anyone comfortable with the standard library's multithreading APIs and who needs a mutex is probably writing C++ for their application too.

From this point of view, I really like a lot of Arduino_Threads.

[rogernolan]

@dsyleixa i think there are useful applications where someone without much experience just wants to make a device that does two independent things: e.g. broadcast IMU data over BT LE and send temperature to ArduinoCloud (this is a real example). I think the intent of the current proposal helps make such a design simpler, clearer and less error prone. Agree that some of the naming is odd but that isn’t (I think) what’s being asked here.

I do agree that there are also areas where more experienced users want more control. And stdlib is a good model for them* - although My belief is that they’re not the main audience for this library. Maybe I’m wrong though :-)

*Even then, I’m not sure std::thread is a state of the art API anymore, it’s kind of old. Better to borrow from e.g. goroutines or GCD.

[dsyleixa]

std::thread is fine, common, handsome, and proven both for e.g. Raspberry Pi (LINUX, C++14, C++18,...) and even ESP32-arduino (freeRTOS), and as to ESP32 it's already kind of actual standard which should also be adopted for common Arduino.
As to @rogernolan:
your argument is useless, even for only 2 single parallel threads std::thread is dead simple, no extra files, just 2 simple declarations for the already existing functions to make them run in independant threads (also for multicore-boards!):

  thread  thread1(broadcast_IMU_data);     // starting 1st std::thread
  thread  thread2(send_temperature_to_ArduinoCloud);     // starting 2nd std::thread

what could actually be more simple?

[rei-vilo]

I think there are two very different audiences for multithreading on Arduino. The difference between them is encapsulated in the Arduino API Style Guide with:

Assume you are writing an API for an intelligent person who has not programmed before

When I started working with multithreading, I faced two main challenges: designing the threads (how to break a real case into different tasks) and orchestrating them (how to deal with events, how to communicate between threads, how to share common resources).

Luring "intelligent person[s] who [have] not programmed before" by an easy syntax and omitting the underneath complexity would not be fair.

Before I could develop and use the Galaxia Library, I attended the MOOC Embedded Systems - Shape The World: Multi-Threaded Interfacing from the University of Texas at Austin.

Should Arduino decide to release multithreading capabilities, they should come with extensive learning tutorials.

Thank you!

[dsyleixa]

@rei-vilo
I was learning MT by programming mobile Lego Mindstorms RCX and NXT robots, mainly with the C-like Bytecode-Interpreter Languages NQC and NXC (by Dave Baum and John Hansen IIRC).
They both are using an only very slightly different MT syntax:
start thread (threadname)
whilst the called thread function itself (which then starts running parallel, autonomously) could be written like any common C function in the same code text file.
This architecture was very intuitive and extremely easy to learn.
And that is actually the same concept as std::thread uses, and so it's deadsimple to learn also for Arduino users.

[aentinger]

Should Arduino decide to release multithreading capabilities, they should come with extensive learning tutorials.

Duly noted =)

[rogernolan]

I’m thinking about the cognitive load on someone who really doesn’t need to understand what std::thread does. Ask a non tech friend to read this :-) The separation into files might seem pointless to you but - I believe - you’re not the audience for this API. Whatever, this feels like opinion: my argument certainly is so I’ll bow out now.

…

On 16 Nov 2022 at 14:51 +0000, dsyleixa ***@***.***>, wrote: std::thread is fine, common, handsome, and proven both for e.g. Raspberry Pi (LINUX, C++14, C++18,...) and even ESP32-arduino (freRTOS), and as to ESP32 it's already kind of actual standard which should also be adopted for common Arduino. As to @rogernolan: your argument is useless, even for only 2 simple threads std::thread is dead simple, no extra files, just 2 simple declarations for the already existing functions to make them run in independant threads: thread thread1(broadcast_IMU_data); // starting 1st std::thread thread thread2(send_temperature_to_ArduinoCloud); // starting 2nd std::thread what could actually be more simple? — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>

[dsyleixa]

you are right, I am successfully using std::thread for my ESP32 already by the Arduino-IDE/API since many years (and also for my Raspis), and tbh, I don't have to waste a single thought on why and how std::thread works so smoothly - neither for RTOS nor for Linux boards 8-)
And I won't ever purchase a new original Arduino board any more if just solely the Arduino MT lib was available. ;-)

[glutio]

Hi, I would like to revive this thread regarding what the API could look like. I agree that fun quickly turns into 'state-machine of doom' and in my version of multitasking for AVR/SAMD I implemented a templated API to allow for strongly typed argument for the thread function. The API also supports nonstatic class methods as thread functions.

template<typename T>
int runTask(void (*task)(T arg), T arg, unsigned stackSize, uint8_t priority);

template<typename T, typename U>
int runTask(const T* instance, void (T::*task)(U arg), unsigned stackSize, uint8_t priority);

Can use it like so (more info at https://github.com/glutio/Taskfun)

void timerTask(int ms) { // any type instead of void*
  while(1) {
     delay(ms);
     // do stuff
  }
}

class Program {
public:
  void timerTask(long ms) { ... }
  void Setup() {
     runTask(this, &Program::timerTask, 1000);
  }
};

Program program; // instance of Program

void setup() {
  noInterruts();
  setupTasks();
  runTask(timerTask, 1000);
  program.Setup();
  interrupts();
}

[greiman]

The API should be simple for beginners to use with two threads that don't need much synchronization.

It should also support sophisticated users and future multi-core processors.

std::thread is probably not a great choice. C++ is too general, C++ must run in environments that do not have a stack so it will need to be extended in non-standard ways. Also the API probably should be callable from C.

POSIX Threads have the advantage of maturity.

For example thread create allows expansion to multi-core processors.

int pthread_create(pthread_t *thread, const pthread_attr_t *attr, void *(*start_routine)(void*), void *arg);

This API and others hide expandability in the type of arguments. pthread_attr_t is the place where stack size and other stuff like which core the thread should run on are hidden. A beginner just uses NULL to get suitable defaults.

You cant find the definition of pthread_attr_t in the standard. The standard just tells where to put it.

The pthread_attr_t, pthread_cond_t, pthread_condattr_t, pthread_key_t, pthread_mutex_t, pthread_mutexattr_t, pthread_once_t, pthread_rwlock_t, pthread_rwlockattr_t and pthread_t types are defined as described in <sys/types.h>.

Often there is even a pthread interface for a RTOS. See this for FreeRTOS.

pthread is an example of how to extend an API without breaking code.

In addition to using pthread_attr_t as a parameter type, you provide functions to set attributes in the struct.

int pthread_attr_init(pthread_attr_t *attr); sets attr to the default values.

Functions like int pthread_attr_setstacksize (pthread_attr_t *attr, size_t stacksize) set an attribute.

So a program does not need to be modified unless an attribute you use is changed.

There have been attempts at a standard API for RTOSs but none have as much popularity as pthread.

It's probably too late since Arduino is inventing yet another threading API.

[dsyleixa]

I agree that POSIX pthread would be a good choice too, finally C++std::thread is more or less just a wrapper to pthread (and still uses pthread for e.g. thread prio etc...).
And finally all and everything as to Arduino API is just about API wrappers.
Nonetheless the std::thread implementation for arduino-ESP32 runs like charm.

[greiman]

Nonetheless the std::thread implementation for arduino-ESP32 runs like charm.

std::thread is probably fine. If the implementation has the member native_handle you have access to the pthread functions.

[dsyleixa]

I didn't try native_handle on my arduino-ESP32 , just on RPi/Linux, but std::thread for arduino-ESP32 are wrappers around pthread of freeRTOS-API.