From f3555971ada295460d6079bb12dd79fdb632e3a7 Mon Sep 17 00:00:00 2001 From: Alexander Entinger Date: Thu, 9 Jun 2022 06:43:48 +0200 Subject: [PATCH 1/7] Fix: Removing extraneous brace. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index df282d1..bfaa8e4 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ As a result this interruption by the scheduler will break Wire I/O access for bo `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. ### :runner: Asynchronous -The mechanisms implemented in this library allow any thread to dispatch an I/O request asynchronously and either continue its operation or [yield](https://en.wikipedia.org/wiki/Yield_(multithreading)) 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](https://en.wikipedia.org/wiki/Context_switch). An example of this can be seen [here](examples/Threadsafe_IO/Threadsafe_SPI/Threadsafe_SPI.ino)). +The mechanisms implemented in this library allow any thread to dispatch an I/O request asynchronously and either continue its operation or [yield](https://en.wikipedia.org/wiki/Yield_(multithreading)) 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](https://en.wikipedia.org/wiki/Context_switch). An example of this can be seen [here](examples/Threadsafe_IO/Threadsafe_SPI/Threadsafe_SPI.ino). ### :relieved: Convenient API Although you are free to directly manipulate I/O requests and responses (e.g. [Threadsafe_Wire](examples/Threadsafe_IO/Threadsafe_Wire/Threadsafe_Wire.ino)) there are convenient `read`/`write`/`write_then_read` abstractions inspired by the [Adafruit_BusIO](https://github.com/adafruit/Adafruit_BusIO) library (e.g. [Threadsafe_Wire_BusIO](examples/Threadsafe_IO/Threadsafe_Wire_BusIO/Threadsafe_Wire_BusIO.ino)). From fe1b9dd98cb2ce01abf1972e973d43b48c068d2a Mon Sep 17 00:00:00 2001 From: Alexander Entinger Date: Thu, 9 Jun 2022 06:49:48 +0200 Subject: [PATCH 2/7] Pointing towards documentation. --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index bfaa8e4..0856114 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ This library makes it easy to use the multi-threading capability of [Arduino](https://www.arduino.cc/) boards that use an [Mbed OS](https://os.mbed.com/docs/mbed-os/latest/introduction/index.html)-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 is available within the [`/docs`](docs/README.md) subfolder. + ## :star: Features ### :thread: 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 **t**hread) representing a clear separation of concerns on a file level. From a201cd20e6c1c7cb567f2633c6c4bcbe6b910eac Mon Sep 17 00:00:00 2001 From: Alexander Entinger Date: Thu, 9 Jun 2022 06:50:08 +0200 Subject: [PATCH 3/7] Adding note on the libraries BETA-ness and suggested input. --- README.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/README.md b/README.md index 0856114..b78d186 100644 --- a/README.md +++ b/README.md @@ -50,12 +50,9 @@ The mechanisms implemented in this library allow any thread to dispatch an I/O r ### :relieved: Convenient API Although you are free to directly manipulate I/O requests and responses (e.g. [Threadsafe_Wire](examples/Threadsafe_IO/Threadsafe_Wire/Threadsafe_Wire.ino)) there are convenient `read`/`write`/`write_then_read` abstractions inspired by the [Adafruit_BusIO](https://github.com/adafruit/Adafruit_BusIO) library (e.g. [Threadsafe_Wire_BusIO](examples/Threadsafe_IO/Threadsafe_Wire_BusIO/Threadsafe_Wire_BusIO.ino)). - - ## :zap: Caveats - - +This library is currently in **BETA** stage. This means that neither the API nor the usage patters 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 as an experiment and ask for your input for shaping this library into a useful tool. Please help us by providing feedback on the [issues](https://github.com/bcmi-labs/Arduino_Threads/issues) or participating in our [discussions](https://github.com/arduino/ArduinoCore-API/discussions). ## :mag_right: Resources From 01d96e1d8872ca2e021597c4c48e36bcf58c2231 Mon Sep 17 00:00:00 2001 From: Alexander Entinger Date: Thu, 9 Jun 2022 06:50:59 +0200 Subject: [PATCH 4/7] Adding top-level BETA note. --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index b78d186..e2e0bcb 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ `Arduino_Threads` ================= +*Note: This library is currently in BETA.* [![Compile Examples status](https://github.com/arduino-libraries/Arduino_Threads/actions/workflows/compile-examples.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_Threads/actions/workflows/compile-examples.yml) [![Check Arduino status](https://github.com/arduino-libraries/Arduino_Threads/actions/workflows/check-arduino.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_Threads/actions/workflows/check-arduino.yml) From 02773c868a1f06ef60869bb98a8e8dbf140f0215 Mon Sep 17 00:00:00 2001 From: Alexander Entinger Date: Thu, 9 Jun 2022 10:53:57 +0200 Subject: [PATCH 5/7] Add in-page link to directly lead to the caveats associated with the beta stage. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e2e0bcb..9936145 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ `Arduino_Threads` ================= -*Note: This library is currently in BETA.* +*Note: This library is currently in [beta](#zap-caveats).* [![Compile Examples status](https://github.com/arduino-libraries/Arduino_Threads/actions/workflows/compile-examples.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_Threads/actions/workflows/compile-examples.yml) [![Check Arduino status](https://github.com/arduino-libraries/Arduino_Threads/actions/workflows/check-arduino.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_Threads/actions/workflows/check-arduino.yml) From 8b94500063f468dd1baab24fea0bb5a271bea697 Mon Sep 17 00:00:00 2001 From: Alexander Entinger Date: Thu, 9 Jun 2022 10:55:31 +0200 Subject: [PATCH 6/7] Also mention the necessity of specific tooling. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9936145..7dcd19e 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ This library makes it easy to use the multi-threading capability of [Arduino](https://www.arduino.cc/) boards that use an [Mbed OS](https://os.mbed.com/docs/mbed-os/latest/introduction/index.html)-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 is available within the [`/docs`](docs/README.md) subfolder. +Preeliminary **documentation** and download links for **required tooling** are available within the [`/docs`](docs/README.md) subfolder. ## :star: Features ### :thread: Multi-threaded sketch execution From 58819ccfdd3f537036c32f70810d2d1710cfae52 Mon Sep 17 00:00:00 2001 From: Alexander Entinger Date: Fri, 10 Jun 2022 07:19:55 +0200 Subject: [PATCH 7/7] Update README.md Co-authored-by: Sebastian Romero --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7dcd19e..0862c29 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ Although you are free to directly manipulate I/O requests and responses (e.g. [T ## :zap: Caveats -This library is currently in **BETA** stage. This means that neither the API nor the usage patters 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 as an experiment and ask for your input for shaping this library into a useful tool. Please help us by providing feedback on the [issues](https://github.com/bcmi-labs/Arduino_Threads/issues) or participating in our [discussions](https://github.com/arduino/ArduinoCore-API/discussions). +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](https://github.com/bcmi-labs/Arduino_Threads/issues) or participating in our [discussions](https://github.com/arduino/ArduinoCore-API/discussions). ## :mag_right: Resources