Idle interface

TODO.md

@@ -12,7 +12,7 @@
 - [x] Non-locking `get()` interface
   - [x] Rename old interface to make it clearer it blocks
 - [x] Apply execution policies
-- [ ] `idle()` interface
+- [x] `idle()` interface
   - [x] Rename `running()` to remove ambiguity
 - [x] Use `std::invoke` wherever applicable
 - [x] Prohibit reference outputs (mutable lvalue reference parameters already invalid)

examples/00_introduction.cpp

@@ -50,6 +50,11 @@ int main() {
     std::cout << "Pipeline is empty, can't get another result!\n";
   }
 
+  // We can verify all threads on the pipeline are waiting for input with idle()
+  // Note: idle() may return false if any pipeline stage hasn't registered its idle state yet.
+  // To guarantee the pipeline is idle before exitting, see the next example.
+  std::cout << "pipeline.idle() = " << std::boolalpha << pipeline.idle() << std::endl;
+
   // At the end, we don't need to do anything.
   // The pipeline stops all threads when its destructor is called.
 }

examples/01_consumer_threads.cpp

@@ -35,13 +35,11 @@ int main() {
   pipeline.input(2, 3.5);
   pipeline.input(7, 0.75);
 
-  // We can wait a little, do anything else, and the production will be done.
-  // Sometimes we want to guarantee the pipeline has finished running.
-  // For that, we'll use the idle() member function.
-  // TODO
-  using namespace std::chrono_literals;
-  std::this_thread::sleep_for(100ms);
-
-  // The capture we used from the lambda!
+  // We can wait a little, do anything else, and the processing will be done.
+  // Sometimes we want to guarantee the pipeline has finished running before exitting.
+  // For that, we'll use the wait_until_idle() member function.
+  pipeline.wait_until_idle();
+
+  // The capture we used from the lambda shows us we have processed everything!
   std::cout << "print() has been called " << count << " times.\n";
 }

examples/07_reference_parameters.cpp

@@ -33,7 +33,7 @@ int main() {
   pipeline.input("!dlroW olleH");
   pipeline.input("TACOCAT");
 
-  // We insert a delay before destruction, so the pipeline finishes execution.
-  using namespace std::chrono_literals;
-  std::this_thread::sleep_for(100ms);
+  // We wait until execution is complete with wait_until_idle()
+  // This way, we free the processor from scheduling this thread until then, and don't need to check pipeline.idle()
+  pipeline.wait_until_idle();
 }