Update README

Author: gilzoide

README.md

@@ -1,15 +1,28 @@
 # Dispatch Queue
-Dispatch Queue / Thread Pool implementation for C++11.
+Dispatch Queue / Thread Pool implementation for C++11 with built-in C++20 coroutine support.
 
 
 ## Features
-- No external dependencies: uses only C++11 threading functionality
-- `dispatch` method with API similar to [std::async](https://en.cppreference.com/w/cpp/thread/async): receives a functor and its arguments, returns a `std::future`
-- `dispatch_forget` for a "fire and forget" style call, which avoids the overhead of creating the `std::future`
-- Supports both synchronous (immediate) and asynchronous (threaded) execution.
-  + Asynchronous dispatch queues are also known as Thread Pools
-  + Synchronous dispatch queues are useful for multiplatform code that must work on platforms without thread support, for example WebAssembly on browsers that lack `SharedArrayBuffer` support
-- Single implementation file [src/dispatch_queue.cpp](src/dispatch_queue.cpp), easy to integrate in any project
+- No external dependencies: uses only the C++ STL
+- Supports both immediate and threaded execution modes:
+  + Threaded dispatch queues are also known as Thread Pools.
+    In threaded mode it is safe to dispatch new tasks from any thread.
+  + In immediate mode tasks are executed immediately. Useful for multiplatform code that must work on platforms without thread support, for example WebAssembly on browsers that lack `SharedArrayBuffer` support.
+- Use `dispatch_queue.dispatch(f, args...)` to dispatch new tasks
+- Use `dispatch_queue.dispatch_main(f, args...)` to dispatch "main loop" tasks
+  + Users must call `dispatch_queue.main_loop()` manually where appropriate to run queued main loop tasks
+  + Useful for synchronizing state calculated in background tasks with the application's main loop
+- Returned `dispatch_queue::task<T>` from dispatch methods are similar to `std::shared_future`, with the following additions:
+  + Use `task.get_state()` to get whether task is pending, ready or failed with exception
+  + Use `task.then(f)` to add a continuation function that runs when task finishes
+  + Use `task.get_exception()` to get stored exception_ptr
+- Built-in C++20 coroutine support
+  + Use `dispatch_queue::task<T>` as the return value for your coroutines
+  + `co_await` other tasks to resume the coroutine as the task's continuation
+  + Use `co_await dispatch_queue.dispatch()` to continue coroutine in a dispatch queue's background loop
+  + Use `co_await dispatch_queue.dispatch_main()` to continue coroutine in a dispatch queue's main loop
+- Supports compiling with `-fno-exceptions` and `-fno-rtti`
+- Unified implementation file [src/dispatch_queue-one.cpp](src/dispatch_queue-one.cpp), easy to integrate in any project
 
 
 ## Usage example
@@ -20,14 +33,14 @@ Dispatch Queue / Thread Pool implementation for C++11.
 // 1. Create a dispatch queue
 ///////////////////////////////////////////////////////////
 
-// Default constructed dispatch queues are synchronous.
-// They execute tasks immediately in the same thread that called `dispatch`.
-dispatch_queue::dispatch_queue synchronous_dispatcher;
-// Dispatch queues with 0 threads are also synchronous.
-dispatch_queue::dispatch_queue synchronous_dispatcher2(0);
+// Default constructed dispatch queues are immediate.
+// They execute tasks immediately in the call to `dispatch`.
+dispatch_queue::dispatch_queue immediate_dispatcher;
+// Dispatch queues with 0 threads are also immediate.
+dispatch_queue::dispatch_queue immediate_dispatcher2(0);
 
-// A dispatch queue with 1 thread is called a serial queue:
-// it only runs a single task at a time.
+// A dispatch queue with 1 thread is a serial queue:
+// it runs a single task at a time in its background thread.
 dispatch_queue::dispatch_queue serial_dispatcher(1);
 
 // A dispatch queue with more than 1 thread runs tasks concurrently.
@@ -42,24 +55,75 @@ dispatch_queue::dispatch_queue concurrent_dispatcher2(-1);
 // 2. Dispatch some tasks!
 ///////////////////////////////////////////////////////////
 
-// Use the returned future to get results or wait for completion.
-auto task = []() { return 42; };
-std::future<int> async_result = dispatcher.dispatch(task);
-assert(async_result.get() == 42);
+// Use the returned task to get results or wait for completion.
+auto work = []{ return 42; };
+dispatch_queue::task<int> task = dispatcher.dispatch(work);
+assert(task.get() == 42);
 
 // Pass arguments to forward to task
-auto task2 = [](int value) { return value; };
-std::future<int> async_result2 = dispatcher.dispatch(task2, 2);
-assert(async_result2.get() == 2);
+auto work2 = [](int value) { return value; };
+dispatch_queue::task<int> task2 = dispatcher.dispatch(work2, 2);
+assert(task2.get() == 2);
+
+// Use `then` for adding continuations
+dispatch_queue::task<void> continued_task = dispatcher.dispatch(work)
+    // continuations receive the finished task
+    .then([](dispatch_queue::task<int> task) {
+        if (std::exception_ptr exception = task.get_exception()) {
+            // task failed with an exception...
+            std::rethrow_exception(exception);
+        }
+        else {
+            // task succeeded!
+            int result = task.get();
+            return (float) result;
+        }
+    })
+    // .then() return a new task, so you can chain continuations
+    .then([&](dispatch_queue::task<float> task) {
+        return dispatcher.dispatch(work2);
+    })
+    // .then() unwraps task<task<T>> if C++20 concepts are available
+    .then([](dispatch_queue::task<int> task) {
+        return;
+    });
+continued_task.wait();
+
+// Queue "main loop" tasks that will be executed by calling `main_loop()`
+dispatcher.dispatch_main([]{
+    std::cout << "This will run inside the call to `main_loop`" << std::endl;
+});
+while (!ApplicationShouldExit()) {
+    // Inside your application's main loop...
+    dispatcher.main_loop();
+}
+
+
+///////////////////////////////////////////////////////////
+// 3. Built-in C++20 coroutine support
+///////////////////////////////////////////////////////////
+
+// Use dispatch_queue::task<T> as return value for coroutines
+dispatch_queue::task<void> my_coro() {
+    // co_await other tasks
+    // coroutine becomes task's continuation via .then()
+    co_await dispatcher.dispatch(some_work);
+    do_something_after_some_work_finished();
+
+    // co_await .dispatch()
+    // coroutine continues within dispatch queue
+    co_await dispatcher.dispatch();
+    do_something_in_background();
 
-// For "fire and forget" calls, use `dispatch_forget`.
-// This avoids the overhead of creating `std::future`.
-dispatcher.dispatch_forget(task);
-dispatcher.dispatch_forget(task2, 2);
+    // co_await .dispatch_main()
+    // coroutine continues within dispatch queue's main loop
+    co_await dispatcher.dispatch_main();
+    do_something_in_main_loop();
+}
 
 
 ///////////////////////////////////////////////////////////
-// 3. Check some stats
+// 4. Check some stats
 ///////////////////////////////////////////////////////////
 
 int dispatcher_thread_count = dispatcher.thread_count();
@@ -69,7 +133,7 @@ bool has_no_pending_tasks = dispatcher.empty();
 
 
 ///////////////////////////////////////////////////////////
-// 4. Other operations
+// 5. Other operations
 ///////////////////////////////////////////////////////////
 
 // Cancel all pending tasks.
@@ -87,7 +151,7 @@ dispatcher.wait_until(std::chrono::system_clock::now() + std::chrono::seconds(5)
 ## Using in CMake projects
 Add this project using `add_subdirectory` and link your target to `dispatch_queue`:
 ```cmake
-add_subdirectory(path/to/dispatch_queue)
+add_subdirectory("path/to/dispatch_queue")
 target_link_libraries(my_target dispatch_queue)
 ```