From fe55b9f4d138f3b999de581d378345b61a9cc5bd Mon Sep 17 00:00:00 2001 From: Alexander Entinger Date: Mon, 6 Dec 2021 15:05:28 +0100 Subject: [PATCH] Cleaning up/adding missing comments within examples. This is done in order to put clearer into context what actually is happening. --- examples/Breaks_6/Breaks_6.ino | 4 ++++ .../Threading_Basics/Shared_Counter/Consumer.inot | 6 ++++++ .../Threading_Basics/Shared_Counter/Producer.inot | 4 ++++ .../Shared_Counter/SharedVariables.h | 1 + .../Shared_Counter/Shared_Counter.ino | 5 +++++ .../Source_Sink_Counter/Consumer.inot | 1 + .../Source_Sink_Counter/Producer.inot | 1 + .../Source_Sink_Counter/Source_Sink_Counter.ino | 7 +++---- .../Source_Sink_LED/Sink_Thread.inot | 12 ++++-------- .../Source_Sink_LED/Source_Sink_LED.ino | 7 +++---- .../Source_Sink_LED/Source_Thread.inot | 2 +- examples/Threadsafe_IO/SPI/SPI.ino | 6 ++++++ examples/Threadsafe_IO/SPI_BusIO/SPI_BusIO.ino | 9 +++++++++ .../Serial_GlobalPrefixSuffix.ino | 7 +++++++ .../Serial_ProtocolWrapping.ino | 7 +++++++ .../Threadsafe_IO/Serial_Reader/Serial_Reader.ino | 6 ++++++ .../Threadsafe_IO/Serial_Writer/Serial_Writer.ino | 5 +++++ examples/Threadsafe_IO/Wire/Wire.ino | 6 ++++++ examples/Threadsafe_IO/Wire_BusIO/Wire_BusIO.ino | 11 ++++++++++- 19 files changed, 89 insertions(+), 18 deletions(-) diff --git a/examples/Breaks_6/Breaks_6.ino b/examples/Breaks_6/Breaks_6.ino index e56c606..86b3bfa 100644 --- a/examples/Breaks_6/Breaks_6.ino +++ b/examples/Breaks_6/Breaks_6.ino @@ -1,3 +1,7 @@ +/* This example is in fact expected to break, since we try + * to access a thread-private variable. + */ + #include void setup() diff --git a/examples/Threading_Basics/Shared_Counter/Consumer.inot b/examples/Threading_Basics/Shared_Counter/Consumer.inot index 5030a61..c03efd9 100644 --- a/examples/Threading_Basics/Shared_Counter/Consumer.inot +++ b/examples/Threading_Basics/Shared_Counter/Consumer.inot @@ -6,5 +6,11 @@ void setup() void loop() { + /* If a value is available for reading within the internal + * queue then the value is removed from the queue and made + * available to the calling function. Should no data be + * available, then this thread is suspended until new data + * is available for reading. + */ Serial.println(counter); } diff --git a/examples/Threading_Basics/Shared_Counter/Producer.inot b/examples/Threading_Basics/Shared_Counter/Producer.inot index 59a76a9..7475653 100644 --- a/examples/Threading_Basics/Shared_Counter/Producer.inot +++ b/examples/Threading_Basics/Shared_Counter/Producer.inot @@ -6,6 +6,10 @@ void setup() void loop() { static int i = 0; + /* Every 100 ms a new value is inserted into the shared variable + * 'counter'. Internally this is stored within a queue in a FIFO + * (First-In/First-Out) manner. + */ counter = i; i++; delay(100); diff --git a/examples/Threading_Basics/Shared_Counter/SharedVariables.h b/examples/Threading_Basics/Shared_Counter/SharedVariables.h index 5891a84..7cc8c0c 100644 --- a/examples/Threading_Basics/Shared_Counter/SharedVariables.h +++ b/examples/Threading_Basics/Shared_Counter/SharedVariables.h @@ -1 +1,2 @@ +/* Define a shared variable named 'counter' of type 'int'. */ SHARED(counter, int); diff --git a/examples/Threading_Basics/Shared_Counter/Shared_Counter.ino b/examples/Threading_Basics/Shared_Counter/Shared_Counter.ino index 2577997..87f7007 100644 --- a/examples/Threading_Basics/Shared_Counter/Shared_Counter.ino +++ b/examples/Threading_Basics/Shared_Counter/Shared_Counter.ino @@ -1,3 +1,8 @@ +/* This example demonstrates data exchange between + * threads using a shared counter variable defined + * within 'SharedVariables.h'. + */ + void setup() { Producer.start(); diff --git a/examples/Threading_Basics/Source_Sink_Counter/Consumer.inot b/examples/Threading_Basics/Source_Sink_Counter/Consumer.inot index 57b217a..5ae30b5 100644 --- a/examples/Threading_Basics/Source_Sink_Counter/Consumer.inot +++ b/examples/Threading_Basics/Source_Sink_Counter/Consumer.inot @@ -1,3 +1,4 @@ +/* Define a data sink named 'counter' of type 'int' with a internal queue size of 10. */ SINK(counter, int, 10); void setup() diff --git a/examples/Threading_Basics/Source_Sink_Counter/Producer.inot b/examples/Threading_Basics/Source_Sink_Counter/Producer.inot index a038d37..3938a1c 100644 --- a/examples/Threading_Basics/Source_Sink_Counter/Producer.inot +++ b/examples/Threading_Basics/Source_Sink_Counter/Producer.inot @@ -1,3 +1,4 @@ +/* Define a data source named 'counter' of type 'int'. */ SOURCE(counter, int); void setup() diff --git a/examples/Threading_Basics/Source_Sink_Counter/Source_Sink_Counter.ino b/examples/Threading_Basics/Source_Sink_Counter/Source_Sink_Counter.ino index e2c1363..f237bb2 100644 --- a/examples/Threading_Basics/Source_Sink_Counter/Source_Sink_Counter.ino +++ b/examples/Threading_Basics/Source_Sink_Counter/Source_Sink_Counter.ino @@ -1,7 +1,6 @@ -/* - * This examples demonstrates the SOURCE/SINK abstraction. - * Each thread may have any number of SOURCES and SINKS that can be connected - * together using the "connectTo" method. +/* This examples demonstrates the SOURCE/SINK abstraction. Each thread + * may have any number of SOURCES and SINKS that can be connected + * together using the 'connectTo' method. */ void setup() diff --git a/examples/Threading_Basics/Source_Sink_LED/Sink_Thread.inot b/examples/Threading_Basics/Source_Sink_LED/Sink_Thread.inot index 14a9723..369de6b 100644 --- a/examples/Threading_Basics/Source_Sink_LED/Sink_Thread.inot +++ b/examples/Threading_Basics/Source_Sink_LED/Sink_Thread.inot @@ -1,8 +1,4 @@ - -/* - * An 'bool' SINK with a size of '0'. This kind of SINK has no buffer so the reading thread - * will block until the writing thread has written something, or vice versa. - */ +/* Define a data sink named 'led' of type 'bool' with a internal queue size of 1. */ SINK(led, bool); void setup() @@ -12,9 +8,9 @@ void setup() void loop() { - /* Read a 'bool' from the SINK and discard it. Since there is basically no delay in the loop - * this call will surely block until something comes from the connected SOURCE. In this case - * the pace is dictated by the SOURCE that sends data every 100 ms. + /* Read a 'bool' value from the SINK and discard it. Since there is no delay in the loop + * this call will block until new data is inserted from the connected SOURCE. This means + * that the pace is dictated by the SOURCE that sends data every 100 ms. */ digitalWrite(LED_BUILTIN, led); } diff --git a/examples/Threading_Basics/Source_Sink_LED/Source_Sink_LED.ino b/examples/Threading_Basics/Source_Sink_LED/Source_Sink_LED.ino index 48ddafc..c0e94be 100644 --- a/examples/Threading_Basics/Source_Sink_LED/Source_Sink_LED.ino +++ b/examples/Threading_Basics/Source_Sink_LED/Source_Sink_LED.ino @@ -1,7 +1,6 @@ -/* - * This examples demonstrates the SOURCE/SINK abstraction. - * Each thread may have any number of SOURCES and SINKS that can be connected - * together using the "connectTo" method. +/* This examples demonstrates the SOURCE/SINK abstraction. Each thread + * may have any number of SOURCES and SINKS that can be connected + * together using the 'connectTo' method. */ void setup() diff --git a/examples/Threading_Basics/Source_Sink_LED/Source_Thread.inot b/examples/Threading_Basics/Source_Sink_LED/Source_Thread.inot index 4585f85..78be7f4 100644 --- a/examples/Threading_Basics/Source_Sink_LED/Source_Thread.inot +++ b/examples/Threading_Basics/Source_Sink_LED/Source_Thread.inot @@ -1,4 +1,4 @@ -/* The output SOURCE, it sends 'bool' values. */ +/* Define a data source named 'led' of type 'bool'. */ SOURCE(led, bool); void setup() diff --git a/examples/Threadsafe_IO/SPI/SPI.ino b/examples/Threadsafe_IO/SPI/SPI.ino index b24a2ee..333299a 100644 --- a/examples/Threadsafe_IO/SPI/SPI.ino +++ b/examples/Threadsafe_IO/SPI/SPI.ino @@ -1,3 +1,9 @@ +/* This example demonstrates how multiple threads can communicate + * with a single SPI client device using the BusDevice abstraction + * for SPI. In a similar way multiple threads can interface + * with different client devices on the same SPI bus. + */ + /************************************************************************************** * INCLUDE **************************************************************************************/ diff --git a/examples/Threadsafe_IO/SPI_BusIO/SPI_BusIO.ino b/examples/Threadsafe_IO/SPI_BusIO/SPI_BusIO.ino index 5ebf5f5..863d3e3 100644 --- a/examples/Threadsafe_IO/SPI_BusIO/SPI_BusIO.ino +++ b/examples/Threadsafe_IO/SPI_BusIO/SPI_BusIO.ino @@ -1,3 +1,12 @@ +/* This example demonstrates how multiple threads can communicate + * with a single SPI client device using the BusDevice abstraction + * for SPI. In a similar way multiple threads can interface + * with different client devices on the same SPI bus. + * + * This example uses Adafruit_BusIO style read(), write(), + * write_then_read() APIs. + */ + /************************************************************************************** * INCLUDE **************************************************************************************/ diff --git a/examples/Threadsafe_IO/Serial_GlobalPrefixSuffix/Serial_GlobalPrefixSuffix.ino b/examples/Threadsafe_IO/Serial_GlobalPrefixSuffix/Serial_GlobalPrefixSuffix.ino index e514c04..1121b1f 100644 --- a/examples/Threadsafe_IO/Serial_GlobalPrefixSuffix/Serial_GlobalPrefixSuffix.ino +++ b/examples/Threadsafe_IO/Serial_GlobalPrefixSuffix/Serial_GlobalPrefixSuffix.ino @@ -1,3 +1,10 @@ +/* This example demonstrates how every Serial message can be prefixed + * as well as suffixed by a user-configurable message. In this example + * this functionality is used for appending the current timestamp and + * prepending a line feed. Other uses might be to prepend the thread + * from which a given serial message is originating. + */ + /************************************************************************************** * INCLUDE **************************************************************************************/ diff --git a/examples/Threadsafe_IO/Serial_ProtocolWrapping/Serial_ProtocolWrapping.ino b/examples/Threadsafe_IO/Serial_ProtocolWrapping/Serial_ProtocolWrapping.ino index a9632df..7faffb0 100644 --- a/examples/Threadsafe_IO/Serial_ProtocolWrapping/Serial_ProtocolWrapping.ino +++ b/examples/Threadsafe_IO/Serial_ProtocolWrapping/Serial_ProtocolWrapping.ino @@ -1,3 +1,10 @@ +/* This example demonstrates how every Serial message can be prefixed + * as well as suffixed by a user-configurable message. In this example + * this functionality is used for prepending the right header for a + * pseudo NMEA-encoded (think GPS) message as well as for calculating + * and appending the checksum at the end. + */ + /************************************************************************************** * INCLUDE **************************************************************************************/ diff --git a/examples/Threadsafe_IO/Serial_Reader/Serial_Reader.ino b/examples/Threadsafe_IO/Serial_Reader/Serial_Reader.ino index 3e8aa86..16dad9e 100644 --- a/examples/Threadsafe_IO/Serial_Reader/Serial_Reader.ino +++ b/examples/Threadsafe_IO/Serial_Reader/Serial_Reader.ino @@ -1,3 +1,9 @@ +/* This example demonstrates how multiple threads can subscribe to + * reading from the same physical Serial interface. Incoming data + * is copied into per-thread receive buffers so that no thread + * can "steal" data from another thread by reading it first. + */ + /************************************************************************************** * INCLUDE **************************************************************************************/ diff --git a/examples/Threadsafe_IO/Serial_Writer/Serial_Writer.ino b/examples/Threadsafe_IO/Serial_Writer/Serial_Writer.ino index 3759ab2..d019492 100644 --- a/examples/Threadsafe_IO/Serial_Writer/Serial_Writer.ino +++ b/examples/Threadsafe_IO/Serial_Writer/Serial_Writer.ino @@ -1,3 +1,8 @@ +/* This example demonstrates how multiple threads can write to + * the same physical Serial interface without interfering with + * one another. + */ + /************************************************************************************** * INCLUDE **************************************************************************************/ diff --git a/examples/Threadsafe_IO/Wire/Wire.ino b/examples/Threadsafe_IO/Wire/Wire.ino index 11a7372..543d5e9 100644 --- a/examples/Threadsafe_IO/Wire/Wire.ino +++ b/examples/Threadsafe_IO/Wire/Wire.ino @@ -1,3 +1,9 @@ +/* This example demonstrates how multiple threads can communicate + * with a single Wire client device using the BusDevice abstraction + * for Wire. In a similar way multiple threads can interface + * with different client devices on the same Wire bus. + */ + /************************************************************************************** * INCLUDE **************************************************************************************/ diff --git a/examples/Threadsafe_IO/Wire_BusIO/Wire_BusIO.ino b/examples/Threadsafe_IO/Wire_BusIO/Wire_BusIO.ino index 062841d..d241628 100644 --- a/examples/Threadsafe_IO/Wire_BusIO/Wire_BusIO.ino +++ b/examples/Threadsafe_IO/Wire_BusIO/Wire_BusIO.ino @@ -1,4 +1,13 @@ - /************************************************************************************** +/* This example demonstrates how multiple threads can communicate + * with a single Wire client device using the BusDevice abstraction + * for Wire. In a similar way multiple threads can interface + * with different client devices on the same Wire bus. + * + * This example uses Adafruit_BusIO style read(), write(), + * write_then_read() APIs. + */ + +/************************************************************************************** * INCLUDE **************************************************************************************/