[resumable] Deprecate resumable functions

Author: salkinium

README.md

@@ -61,7 +61,6 @@ git clone --recurse-submodules --jobs 8 https://github.com/modm-io/modm.git
     - UART, I<sup>2</sup>C, SPI, CAN and Ethernet.
 - Interfaces and drivers for many external I<sup>2</sup>C and SPI sensors and devices.
 - Debug/logging system with IOStream and printf interface.
-- Cooperative, stackless protothreads and resumable functions.
 - Cooperative, stackful fibers and scheduler.
 - Functional (partial) libstdc++ implementation for AVRs.
 - Useful filter, interpolation and geometric algorithms.

docs/src/how-modm-works.md

@@ -372,64 +372,47 @@ Heap:     197240B (98.2% available)
 
 <!-- (⚡️ requires module documentation for protothread/resumable) -->
 
-modm uses stackless cooperative multitasking, for which we have ported
-protothreads to C++ and extended them with resumable functions.
+modm implements stackful, cooperative fibers and provides a concurrency
+support library based on the C++ interface.
 This enables you to split up your application into separate tasks, and use
 synchronous APIs in all of them, without sacrificing overall responsiveness.
-This works on even the most resource restricted AVRs, since each task only
-requires 2 bytes of static RAM!
-
-All our IC drivers are implemented using resumable functions, which can be
-called from within protothreads or explicitly blocking outside of them.
 Here is an example of [reading out the accelerometer][accel]:
 
 ```cpp
-class ReaderThread : public modm::pt::Protothread
+// This accelerometer is connected via I2C.
+modm::Lis3dsh< modm::Lis3TransportI2c< I2cMaster > > accelerometer;
+modm::filter::MovingAverage<float, 25> averageX;
+modm::filter::MovingAverage<float, 25> averageY;
+modm::Fiber fiber_sensor([]
 {
-public:
-    bool run()
+    // The driver does several I2C transfer here to initialize and configure the
+    // external sensor. The CPU is free to do other things while this happens though.
+    accelerometer.configure(accelerometer.Scale::G2);
+
+    while (true)
     {
-        PT_BEGIN();
-        // The driver does several I2C transfer here to initialize and configure the
-        // external sensor. The CPU is free to do other things while this happens though.
-        PT_CALL(accelerometer.configure(accelerometer.Scale::G2));
-
-        while (true)    // this feels quite similar to regular threads
-        {
-            // this resumable function will defer execution back to other protothreads
-            PT_CALL(accelerometer.readAcceleration());
-
-            // smooth out the acceleration data a little bit
-            averageX.update(accelerometer.getData().getX());
-            averageY.update(accelerometer.getData().getY());
-
-            // set the boards LEDs depending on the acceleration values
-            LedUp::set(   averageX.getValue() < -0.2);
-            LedDown::set( averageX.getValue() >  0.2);
-            LedLeft::set( averageY.getValue() < -0.2);
-            LedRight::set(averageY.getValue() >  0.2);
-
-            // defer back to other protothreads until the timer fires
-            PT_WAIT_UNTIL(timer.execute());
-        }
-        PT_END();
+        // More I2C transfers in the background
+        accelerometer.readAcceleration();
+
+        // smooth out the acceleration data a little bit
+        averageX.update(accelerometer.getData().getX());
+        averageY.update(accelerometer.getData().getY());
+
+        // set the boards LEDs depending on the acceleration values
+        LedUp::set(   averageX.getValue() < -0.2);
+        LedDown::set( averageX.getValue() >  0.2);
+        LedLeft::set( averageY.getValue() < -0.2);
+        LedRight::set(averageY.getValue() >  0.2);
+
+        // defer back to other fiber while this one sleeps
+        modm::this_fiber::sleep_for(5ms);
     }
-private:
-    // This accelerometer is connected via I2C.
-    modm::Lis3dsh< modm::Lis3TransportI2c< I2cMaster > > accelerometer;
-    modm::PeriodicTimer timer = modm::PeriodicTimer(5); // 5ms periodic timer.
-    modm::filter::MovingAverage<float, 25> averageX;
-    modm::filter::MovingAverage<float, 25> averageY;
-};
-ReaderThread reader;    // Protothread is statically allocated!
+});
 
-int main() // Execution entry point.
+int main()
 {
-    while(true)
-    {   // the main loop with implicit round robin cooperative scheduling.
-        reader.run();
-        otherProtothreads.run();
-    }
+    Board::initialize();
+    modm::fiber::Scheduler::run();
     return 0;
 }
 ```

src/modm/processing/fiber/functions.hpp renamed to src/modm/architecture/interface/fiber.hpp

@@ -21,15 +21,15 @@ namespace modm::fiber
 {
 
 /// Identifier of a fiber task.
-/// @ingroup modm_processing_fiber
+/// @ingroup modm_architecture_fiber
 using id = uintptr_t;
 
 } // namespace modm::fiber
 
 namespace modm::this_fiber
 {
 
-/// @ingroup modm_processing_fiber
+/// @ingroup modm_architecture_fiber
 /// @{
 
 /**

src/modm/architecture/interface/fiber.md

@@ -0,0 +1,116 @@
+# Fiber Interface
+
+This module provides an interface to yield control back to a scheduler. The
+basic functionality is provided by the `yield()` function which transparently
+gives control back to the scheduler and returns afterwards. It is particularly
+important to call yield in long running loops to prevent the system from locking
+up and preventing other fibers from making progress:
+
+```cpp
+while(true)
+{
+    // run your code here
+    // but always yield to other fibers whenever possible
+    modm::this_fiber::yield();
+}
+```
+
+For convenience a `poll()` function is provided that can be used to yield until
+a condition is met:
+
+```cpp
+modm::this_fiber::poll([&]{ return condition; });
+```
+
+An extension of this concept is provided by the `poll_for()` and `poll_until()`
+functions, which yield until the condition is met or until a timeout occurs:
+
+```cpp
+bool condition_met = modm::this_fiber::poll_for(1s, [&]{ return condition; });
+// if (not condition_met) condition did not return true for 1s.
+```
+
+If microseconds are passed for the duration, the functions use the
+`modm::chrono::micro_clock` (= `modm::PreciseClock`), otherwise they use
+`modm::chrono::milli_clock` (= `modm::Clock`). This requires that these clocks
+are already initialized and running.
+
+These basic building blocks are then used to implement the `sleep_for()` and
+`sleep_until()` convenience functions:
+
+```cpp
+modm::this_fiber::sleep_for(1s);
+```
+
+
+## Implementation
+
+The `yield()` function is implemented by the `modm:processing:fiber` module
+which provides a cooperative multitasking scheduler that is able to switch
+between multiple fiber contexts.
+
+If `yield()` is called outside of a fiber context, for example, in the `main()`
+function when the scheduler is not yet running, `yield()` will return in-place.
+This mechanism allows for a graceful fallback to a blocking API without changes
+to the code using `yield()`.
+
+```cpp
+modm::Fiber fiber_nonblocking([]
+{
+    modm::Timeout timeout(100ms);
+    timeout.wait(); // non-blocking call!
+});
+int main()
+{
+    modm::Timeout timeout(100ms);
+    timeout.wait(); // blocking call!
+
+    modm::fiber::Scheduler::run()
+    return 0;
+}
+```
+
+This mechanism also supports running modm on devices with very small memories
+where a stackful scheduler may be to resource intensive:
+The `modm:processing:fiber` module is strictly opt-in and if not selected the
+scheduler is not included and the `yield()` function is implemented as an empty
+stub while still allowing for the whole API to be used without changes:
+
+```cpp
+modm::Lis3mdl<I2cMaster1> sensor{};
+int main()
+{
+    sensor.configure(); // blocking but works just fine
+    while(true)
+    {
+        modm::Vector3f magVector;
+        sensor.readMagnetometer(magVector); // another blocking call
+        modm::this_fiber::sleep_for(10ms); // this will wait in place
+    }
+}
+```
+
+Therefore, if you use these functions in your code, only depend on
+`modm:architecture:fiber` and let the user decide on the implementation by
+including `modm:processing:fiber` or not. This compromise allows for a seamless
+transition between different devices and scheduling strategies.
+
+
+## Identifier
+
+You can check what fiber your code is executed in by calling the `get_id()`
+function:
+
+```cpp
+auto id = modm::this_fiber::get_id();
+// if (id == 0) called outside a fiber
+// if (id < 1024) called from inside an interrupt
+// else called from inside a fiber
+```
+
+The returned ID is the address of the currently running fiber object. If called
+outside of a fiber, for example, in the main function before the scheduler is
+running, the function returns `0`. If called inside a ARM Cortex-M interrupt,
+the ID returns the IRQ number. The implementation ensures that all returned
+values are unique and thus allow the ID to be used for tracking ownership of
+various recursive locks, for example.

src/modm/architecture/interface/spi_master.hpp

@@ -68,23 +68,23 @@ class SpiMaster : public ::modm::PeripheralDriver, public Spi
 	setDataOrder(DataOrder order);
 
 	/**
-	 * Request access to the spi master within a context.
-	 * You may acquire the spi master multiple times within the same context.
+	 * Request access to the SPI master within a context.
+	 * You may acquire the SPI master multiple times within the same context.
 	 *
-	 * The configuration handler will only be called when aquiring the spi
+	 * The configuration handler will only be called when acquiring the SPI
 	 * master for the first time (if it is not a `nullptr`).
 	 *
-	 * @warning		Aquires must be balanced with releases of the **same** context!
-	 * @warning		Aquires are persistent even after calling `initialize()`!
+	 * @warning		Acquires must be balanced with releases of the **same** context!
+	 * @warning		Acquires are persistent even after calling `initialize()`!
 	 *
-	 * @return	`0` if another context is using the spi master, otherwise
+	 * @return	`0` if another context is using the SPI master, otherwise
 	 * 			`>0` as the number of times this context acquired the master.
 	 */
 	static uint8_t
 	acquire(void *ctx, ConfigurationHandler handler = nullptr);
 
 	/**
-	 * Release access to the spi master within a context.
+	 * Release access to the SPI master within a context.
 	 *
 	 * @warning		Releases must be balanced with acquires of the **same** context!
 	 * @warning		Releases are persistent even after calling `initialize()`!
@@ -95,37 +95,10 @@ class SpiMaster : public ::modm::PeripheralDriver, public Spi
 	static uint8_t
 	release(void *ctx);
 
-	/**
-	 * Swap a single byte and wait for completion.
-	 *
-	 * @param	data
-	 * 		data to be sent
-	 * @return	received data
-	 */
-	static uint8_t
-	transferBlocking(uint8_t data);
-
-	/**
-	 * Set the data buffers and length with options and starts a transfer.
-	 * This may be hardware accelerated (DMA or Interrupt), but not guaranteed.
-	 *
-	 * @param[in]   tx
-	 *      pointer to transmit buffer, set to `nullptr` to send dummy bytes
-	 * @param[out]  rx
-	 *      pointer to receive buffer, set to `nullptr` to discard received bytes
-	 * @param       length
-	 *      number of bytes to be shifted out
-	 */
-	static void
-	transferBlocking(const uint8_t *tx, uint8_t *rx, std::size_t length);
-
 	/**
 	 * Swap a single byte and wait for completion non-blocking!.
 	 *
-	 * You must call this inside a Protothread or Resumable
-	 * using `PT_CALL` or `RF_CALL` respectively.
-	 * @warning	These methods differ from Resumables by lacking context protection!
-	 * 			You must ensure that only one driver is accessing this resumable function
+	 * @warning	You must ensure that only one driver is accessing this resumable function
 	 * 			by using `acquire(ctx)` and `release(ctx)`.
 	 *
 	 * @param	data
@@ -140,10 +113,7 @@ class SpiMaster : public ::modm::PeripheralDriver, public Spi
 	 * starts a non-blocking transfer.
 	 * This may be hardware accelerated (DMA or Interrupt), but not guaranteed.
 	 *
-	 * You must call this inside a Protothread or Resumable
-	 * using `PT_CALL` or `RF_CALL` respectively.
-	 * @warning	These methods differ from Resumables by lacking context protection!
-	 * 			You must ensure that only one driver is accessing this resumable function
+	 * @warning	You must ensure that only one driver is accessing this resumable function
 	 * 			by using `acquire(ctx)` and `release(ctx)`.
 	 *
 	 * @param[in]   tx

src/modm/architecture/module.lb

@@ -170,6 +170,20 @@ class Delay(Module):
         env.copy("interface/delay.hpp")
 # -----------------------------------------------------------------------------
 
+class Fiber(Module):
+    def init(self, module):
+        module.name = "fiber"
+        module.description = FileReader("interface/fiber.md")
+
+    def prepare(self, module, options):
+        module.depends(":stdc++", ":architecture:clock", ":processing")
+        return True
+
+    def build(self, env):
+        env.outbasepath = "modm/src/modm/architecture"
+        env.copy("interface/fiber.hpp")
+# -----------------------------------------------------------------------------
+
 class Gpio(Module):
     def init(self, module):
         module.name = "gpio"
@@ -389,6 +403,7 @@ def prepare(module, options):
     module.add_submodule(Can())
     module.add_submodule(Clock())
     module.add_submodule(Delay())
+    module.add_submodule(Fiber())
     module.add_submodule(Gpio())
     module.add_submodule(GpioExpander())
     module.add_submodule(I2c())