arduino-libraries/arduino_threads

Simple thread-safe IO for parallel sketch execution. [BETA]

Arduino_Threads

Note: This library is currently in beta.

This library makes it easy to use the multi-threading capability of Arduino boards that use an Mbed OS-based core library. Additionally this library provides thread-safe access to Wire, SPI and Serial which is relevant when creating multi-threaded sketches in order to avoid common pitfalls such as race-conditions and invalid state. ​

Preeliminary documentation and download links for required tooling are available within the /docs subfolder.

⭐ Features

🧵 Multi-threaded sketch execution

Instead of one big state-machine-of-doom you can split your application into multiple independent threads, each with it's own setup() and loop() function. Instead of implementing your application in a single .ino file, each independent thread is implemented in a dedicated .inot file (t suffix stands for thread) representing a clear separation of concerns on a file level.

📲 Easy communication between multiple threads

Easy inter-thread-communication is facilitated via a Shared abstraction object providing thread-safe sink/source semantics allowing to safely exchange data of any type between threads.

🛡️ Thread-safe I/O

A key problem of multi-tasking is the prevention of erroneous state when multiple threads share a single resource. The following example borrowed from a typical application demonstrates the problems resulting from multiple threads accessing a single resource:

Imagine an embedded system where multiple Wire client devices are physically connected to a single Wire server. Each Wire client device is managed by a separate software thread. Each thread polls its Wire client device periodically. Access to the I²C bus is managed via the Wire library and typically follows this pattern:

/* Wire Write Access */
Wire.beginTransmission(address);
Wire.write(value);
// Interrupting the current thread e.g. at this point can lead to an erroneous state
// if another thread performs Wire I/O before the transmission ends.
Wire.endTransmission();

/* Wire Read Access */
Wire.requestFrom(address, bytes)
while(Wire.available()) {
  int value = Wire.read();
}

Since we are using ARM Mbed OS which is a preemptive RTOS for achieving multi-tasking capability and under the assumption that all threads share the same priority (which leads to a round-robin scheduling) it can easily happen that one thread is half-way through its Wire I/O access when the scheduler interrupts its execution and schedules the next thread which in turn starts, continues or ends its own Wire I/O access.

As a result this interruption by the scheduler will break Wire I/O access for both devices and leave the Wire I/O controller in an undefined state 🔥.

Arduino_Threads solves this problem by encapsulating the complete I/O access (e.g. reading from a Wire client device) within a single function call which generates an I/O request to be asynchronously executed by a high-priority I/O thread. The high-priority I/O thread is the only instance which directly communicates with physical hardware.

🏃 Asynchronous

The mechanisms implemented in this library allow any thread to dispatch an I/O request asynchronously and either continue its operation or yield control to the next scheduled thread. All I/O requests are stored in a queue and are executed within a high-priority I/O thread after a context-switch. An example of this can be seen here.

😌 Convenient API

Although you are free to directly manipulate I/O requests and responses (e.g. Wire) there are convenient read/write/writeThenRead abstractions inspired by the Adafruit_BusIO library (e.g. Wire_BusIO).

⚡ Caveats

This library is currently in BETA phase. This means that neither the API nor the usage patterns are set in stone and are likely to change. We are publishing this library in the full knowledge that we can't foresee every possible use-case and edge-case. Therefore we would like to treat this library, while it's in beta phase, as an experiment and ask for your input for shaping this library. Please help us by providing feedback in the issues section or participating in our discussions.

🔎 Resources

• How to install a library
• Help Center - Get help from Arduino's official support team
• Forum - Get support from the community

🐛 Bugs & Issues

If you found an issue in this library, you can submit it to the issue tracker of this repository. Remember to include as much detail as you can about your hardware set-up, code and steps for reproducing the issue. To prevent hardware related incompatibilities make sure to use an original Arduino board.

🧑‍💻 Contribute

There are many ways to contribute:

• Improve documentation and examples
• Fix a bug
• Test open Pull Requests
• Implement a new feature
• Discuss potential ways to improve this library

You can submit your patches directly to this repository as Pull Requests. Please provide a detailed description of the problem you're trying to solve and make sure you test on real hardware.

💛 Donations

This open-source code is maintained by Arduino with the help of the community. We invest a considerable amount of time in testing code, optimizing it and introducing new features. Please consider donating or sponsoring to support our work, as well as buying original Arduino boards which is the best way to make sure our effort can continue in the long term.

arduino_threads's Issues

[Discussion] Shared Variables vs. Source/Sink

If you are not familiar with those concepts and the way they are currently implemented in this library take a look at the documentation and the examples.

• Which way of sharing data between threads would you prefer to use? Why?
• When using shared variables, was there any aspect that you would like to work differently?
• When using source/sink, was there any aspect that you would like to work differently?

CC @facchinm @pnndra @alranel @per1234

[Feature Request] Allow configuration of `Shared` FIFO size on a per `Shared` object basis

Note: Currently all Sharedobjects have the same size, which is a compile-time constant in the library.

Bugs: Typical sketches that do not compile with `arduino-cli` (MT)

This issue contains a list of sketches which contain typical programming paradigms which break when compiling with the current version of the multi-threading supporting arduino-cli, due to the relatively simple wrapping of the whole file within a class.

1) .inot contains both function definition and declaration

Breaks_1.zip

2) Failure to register callback since all functions within the .inot` file are effectively member functions (and not free functions)

Breaks_2.zip

3) Initialisation of static variable fails (due to being a class member instead of a default global variable)

Breaks_3.zip

4) Instantiating any kind of object with constructor within the class fails (obviously)

Breaks_4.zip

One possible fix for all those issues would be to directly instantiate the threading class within the start of the inot file, then only prefix setup/loop with class name, i.e.

+class Thread_1 : public Arduino_Threads
+{
+public:
+  Thread_1 { _tabname = "Thread_1" }
+};

-void setup() {
+void Thread_1::setup() {

-void loop() {
+void Thread_1::loop() {


+Thread_1 thread_1;

@facchinm What do you think? Can you rework the arduino-cli branch to support this?
CC @pnndra

[Feature Request] In addition to operator overloading also provide getters/setters

This request has been made by @sebromero. The intend is to have visible methods for setting and retrieving (getting) data from both shared variables and sink/source abstractions as operator overloading can sometimes confuse the user who expects a certain type of behaviour from a standard operator.

Move source code into src subfolder.

Hi @facchinm 👋

I've been wondering if there's a need (caused by your builder modifications) for all the source files to be located in the top-level library folder or if they can be safely moved into src subfolder?

Only wrap `setup`/`loop` within `.inot`.

Todo ...

Add spell-check/check-arduino/compile-examples-private workflows.

Please also provide a minimal README with badges.

Replace new/delete with SharedPtr

As commented here: #3 (comment) .

Usage of `Arduino_Threads` requires extension of `ArduinoCore-mbed` (Danger of CPU hogging)

In order to avoid CPU hogging by the main thread (loop() of *.ino file) it is necessary to add rtos::ThisThread::yield(); to ArduinoCore-mbed as shown below:

for (;;) {
	loop();
	if (arduino::serialEventRun) arduino::serialEventRun();
+	rtos::ThisThread::yield();
}

For all *.inot defined threads this is automatically done by this code executed after calling the thread's loop() function.

Since this is currently not the case rtos::ThisThread::yield(); is currently called within the main thread of each example (i.e. here) and I think we should rather avoid exposing the raw mbed API to the wider public.

Any side effects you can think of @facchinm?

CC @pnndra @giulcioffi @pennam @MaxPayne86

Create example to highlight advantages of sink/source semantics in certain use cases.

• using multiple sinks consuming from a single source
• ...

Cleanup library to remove redundancies and prepare for launch

redundant definition of queue size

queue size of 0 has the same behaviour of queue size=1 hence it would make sense to move the -1 case (non blocking) to queue size = 0 and handle with queues everything else or, if we want to save a bit, move the current size=0 to size=1

https://github.com/bcmi-labs/Arduino_Threads/blob/01aca729e6480faf5f2571a182fee21b365207cf/src/Arduino_Threads.h#L72

Shared Variables queue issue

it seems to me that the line below is wrong:
https://github.com/bcmi-labs/ArduinoThreads/blob/9f652184c5bbc5356e619b5fbc4e4791ea208de0/Arduino_Threads.h#L17

basically it's putting a reference to the current object in the queue but since the object is not copied, in case two elements are put in the queue these will contain the same pointer and when reading the value both items will return the same as they're reading the member of the object, which in the meantime may even have changed again.
https://github.com/bcmi-labs/ArduinoThreads/blob/9f652184c5bbc5356e619b5fbc4e4791ea208de0/Arduino_Threads.h#L9-L13

if we want to really have a queue of more than one item we need to allocate memory for that and push/pull values from there.

bottom line: do we really need more than one item in the queue?

[Feature Request] Use CamelCase for class member functions

This is mandated by the Arduino API Style Guide.

[Discussion] What use case(s) do you see for multi-threading?

• Did you ever write a program/script in which you wanted to have multiple tasks running in parallel?
• If so, what was the purpose of the program? Was it difficult to achieve?
• Is there an example sketch created with Arduino_Threads that you want to share? If so you can upload it here.

CC @facchinm @pnndra @alranel @per1234

Support `Sink`s with a queue size greater than one

inot-files not supported by Arduino IDE, library does not compile

When trying to open and run the "shared counter" example, I can never get the arduino IDE to open the .inot file type and so the compiler always throws an error when calling producer()/consumer(). Any words of wisdom to trickle down?

C:\Users\jgold\AppData\Local\Temp\.arduinoIDE-unsaved2024129-28668-1l8kexo.higr\Shared_Counter\Shared_Counter.ino: In function 'void setup()':
C:\Users\jgold\AppData\Local\Temp\.arduinoIDE-unsaved2024129-28668-1l8kexo.higr\Shared_Counter\Shared_Counter.ino:8:3: error: 'Producer' was not declared in this scope
   Producer.start();
   ^~~~~~~~
C:\Users\jgold\AppData\Local\Temp\.arduinoIDE-unsaved2024129-28668-1l8kexo.higr\Shared_Counter\Shared_Counter.ino:8:3: note: suggested alternative: 'prog_uchar'
   Producer.start();
   ^~~~~~~~
   prog_uchar
C:\Users\jgold\AppData\Local\Temp\.arduinoIDE-unsaved2024129-28668-1l8kexo.higr\Shared_Counter\Shared_Counter.ino:9:3: error: 'Consumer' was not declared in this scope
   Consumer.start();
   ^~~~~~~~

exit status 1

Compilation error: 'Producer' was not declared in this scope

Rename repository to Arduino_Threads

Hi @facchinm @pnndra ☕

Given that the central header file of this library is called Arduino_Threads.h and the current "fashion" of naming Arduino libraries is to prefix them with Arduino_ I suggest to rename this repository to Arduino_Threads.

Your thoughts?