Changes between Version 29 and Version 30 of BestPracticeHandbook

Timestamp:

May 22, 2015, 1:44:16 PM (7 years ago)

Author:

Niall Douglas

Comment:

--

BestPracticeHandbook

@@ -1243 +1243 @@
 == 17. FUTURE PROOFING: Consider being C++ resumable function ready ==
 
-Never block. Never call anything which blocks.
+This is going to be one of the hardest topics to write about given the highly uncertain present plans for resumable function support in C++ 1z. I base most of the following section on N4402 https://isocpp.org/files/papers/N4402.pdf and conversations with Gor Nishanov at C++ Now 2015, plus on conversations with Oliver Kowalke regarding proposed Boost.Fiber.
+
+Firstly, should you care about being C++ resumable function ready? If your library ever:
+
+* Uses threads.
+* Does i/o.
+* Uses callbacks, including `std::function`.
+
+Then the answer is yes! The current C++ 1z resumable function proposal provides two verbs to work with resumable functions:
+
+1. `await`: suspend the execution of the current function, resuming when the callable passed to `await` finishes execution somewhere else or at some other time. Note that the name of this keyword may change in the future. Use of the `await` keyword always causes the invoking function to return some synchronisation object (often a `future<T>`) with a known `resumable_traits` specialisation, where the default catch all specialisation for any `R(T...)` callable is `std::future<R>`.
+
+ This probably is a bit head wrecky, so let's look at some code:
+
+ {{{#!c++
+// This is some function which schedules some async operation whose result is returned via the future<int>
+extern std::future<int> async_call();
+
+// This is a function which calls async_call ten times, suspending itself while async_call runs.
+std::future<int> accumulate()
+{
+  int total=0;
+  for(size_t n=0; n<10; n++)
+    total+=await async_call();
+  return total;
+}
+
+int main(void)
+{
+  std::cout << "Total is " << accumulate().get() << std::endl;
+  return 0;
+}
+ }}}
+
+ The `await` keyword is rather like range for loops in that it expands into boilerplate. Let's look at the above code but with some of the boilerplate inserted, remembering that C++ 1z futures now have continuations support via the `.then(callable)` member function, and bearing in mind this is a simplified expansion of the boilerplate for the purposes of brevity:
+
+ {{{#!c++
+// This is some function which schedules some async operation whose result is returned via the future<int>
+extern std::future<int> async_call();
+
+// This is a function which calls async_call ten times, suspending itself while async_call runs.
+std::future<int> accumulate()
+{
+  // resumable_traits<R, Ts...> is specialised with the call signature of this function i.e. std::future<int>()
+  // promise_type defaults to a wrap of type R::promise_type, so in this case a wrap of std::promise<int>
+  // Note that constructing the promise wrap type does not necessarily construct the wrapped promise i.e.
+  // actual construction may occur lazily
+  auto __resume_promise(std::resumable_traits<std::future<int>>::promise_type());
+  if(__resume_promise.initial_suspend())
+    return suspend_now();                            // Not expanded for brevity
+
+  int total=0;
+  for(size_t n=0; n<10; n++)
+  {
+    std::future<int> &&__temp=async_call();          // Bind to rvalue ref, no moving
+    if(!__temp.await_ready())                        // defaults to __temp.is_ready()
+    {
+      // The frame allocator defaults to std::allocator<char>
+      auto &&__frame_allocator=std::resumable_traits<std::future<int>>::get_allocator();
+
+      // Internally generated by the compiler to resume me at the resume_me_detached goto label after storing my state into
+      // memory allocated using __frame_allocator
+      unspecified_callable &&__resume_me(__frame_allocator, __resume_promise, resume_me_detached);
+
+      // defaults to __temp.then(__resume_me). __resume_me will be executed immediately after __temp.set_value() by the thread calling set_value().
+      __temp.await_suspend(__resume_me);
+
+      // Return a future for the completion of this function. If the internal promise object is
+      // lazily constructed, now is when it actually occurs
+      return __resume_promise.get_return_object();
+    }
+never_resumed:                                       // This path only taken if function not resumed
+    total+=__temp.await_resume();                    // defaults to __temp.get()
+  }
+  if(__resume_promise.final_suspend())
+    return suspend_now();                            // Not expanded for brevity, jumps to resume_me_addr path
+  return std::make_ready_future(total);              // Cheap optimisation elidable future construction
+  
+
+
+  // *** ALTERNATIVE DETACHED CODE PATH FOR WHEN THE FUNCTION IS RESUMED ***
+  for(size_t n=0; n<10; n++)
+  {
+    std::future<int> &&__temp=async_call();          // Bind to rvalue ref, no moving
+    if(!__temp.await_ready())                        // defaults to __temp.is_ready()
+    {
+      // defaults to __temp.then(__resume_me). __resume_me will be executed immediately after __temp.set_value() by the thread calling set_value().
+      __temp.await_suspend(__resume_me);
+
+      // Suspend myself using previously allocated __resume_me
+      __resume_me.suspend();
+    }
+resume_me_detached:  // This path taken if function ever resumed
+    total+=__temp.await_resume();                    // defaults to __temp.get()
+  }
+  if(__resume_promise.final_suspend())
+    return suspend_now();                            // Not expanded for brevity
+  __resume_promise.set_result(total);                // Signals the earlier returned future
+  // No meaningful return from this function can occur
+}
+
+int main(void)
+{
+  std::cout << "Total is " << accumulate().get() << std::endl;
+  return 0;
+}
+ }}}
+
+ This boilerplate expanded version may still hurt the head, so here is essentially what happens: if `async_call()` ever returns an unsignaled future, `accumulate()` will construct a promise-future pair, allocate memory to store its stack frame, schedule the resumption of its detached self as a continuation of the future returned from `async_call()` and return the newly constructured future to `main()`. When the future returned by `async_call()` is signalled, this schedules the resumption of the detached version of `accumulate()` on the thread it was originally running on. This resumed `accumulate()` may suspend and resume itself many more times on the future returned by repeated calls of `async_call()`, but it eventually will signal the future it returned earlier with the result, unblocking `main()`.
+
+ The `await_ready(), await_suspend()` and `await_resume()` functions are firstly looked up as member functions of the synchronisation type. If not present, they are then looked up as free functions within the same namespace as the synchronisation type with usual overload resolution.
+
+2. `yield`: repeatedly suspends the execution of the current function with the value specified to yield, resuming higher up the call tree with that value output. Note that the name of this keyword may change in the future. Yield can be considered as more boilerplate sugar for a repeated construction of a promise-future pair then repeatedly signalled with some output value until the generating function (i.e. the function calling `yield`) returns, with the sequence of those repeated constructions and signals wrapped into an iterable such that the following just works:
+
+ {{{#!c++
+generator<int> fib(int n)
+{
+  int a = 0;
+  int b = 1;
+  while (n-- > 0)
+  {
+    yield a;
+    auto next = a + b;
+    a = b;
+    b = next;
+  }
+}
+
+int main()
+{
+  for (auto v : fib(35))
+    std::cout << v << std::endl;
+}
+ }}}
+
+ This just works because `generator<int>` provides an iterator at `generator<int>::iterator` and a promise type at `generator<int>::promise_type`. The iterator, when dereferenced, causes a single iteration of `fib()` between the `yield` statements and the value yielded is output by the iterator.
+
+TODO
+
 
 Everything i/o async. Boost.Fiber.