Changes between Version 30 and Version 31 of BestPracticeHandbook

Timestamp:

May 26, 2015, 6:31:33 PM (7 years ago)

Author:

Niall Douglas

Comment:

--

BestPracticeHandbook

@@ -388 +388 @@
 
 {{{#!c++
+// handle_type is some class which takes ownership of a valid file descriptor, closing it on type destruction.
+
 std::shared_ptr<handle_type> openfile(std::filesystem::path path)
 {
@@ -1243 +1245 @@
 == 17. FUTURE PROOFING: Consider being C++ resumable function ready ==
 
-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.
+This is going to be one of the hardest topics to write about given the highly uncertain present plans for resumable function/coroutine 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. Gor also kindly supplied me with a pre-draft N4499.
 
 Firstly, should you care about being C++ resumable function ready? If your library ever:
@@ -1253 +1255 @@
 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>`.
+1. `await`: ''potentially'' suspend the execution of the current function and return a future result now, resuming this function's execution 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:
@@ -1266 +1268 @@
   int total=0;
   for(size_t n=0; n<10; n++)
-    total+=await async_call();
+    total+=await async_call();  // Note the await keyword, this is where the function might suspend
   return total;
 }
@@ -1277 +1279 @@
  }}}
 
- 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:
+ The `await` keyword is rather like range for loops in that it expands into a well specified 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 not actual expansion of the boilerplate for the purposes of brevity:
 
  {{{#!c++
@@ -1286 +1288 @@
 std::future<int> accumulate()
 {
-  // resumable_traits<R, Ts...> is specialised with the call signature of this function i.e. std::future<int>()
+  // coroutine_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()
+
+  // Always dynamically allocate a context on entry to a resumable function (the frame allocator defaults to std::allocator<char>)
+  auto &__frame_allocator=std::coroutine_traits<std::future<int>>::get_allocator();
+  struct __context_type
+  {
+    std::coroutine_traits<std::future<int>>::promise_type __resume_promise;
+    ... <args, stack, state> ...
+  } *__context=__frame_allocator.allocate(sizeof(__context_type));
+
+  // Construct the context frame
+  new (__context) __context_type(<args, stack, state>);
+
+  // Generate a future for the completion of this function
+  auto __return_object(__context->__resume_promise.get_return_object());
+  
+  if(__context->__resume_promise.initial_suspend())
+    return suspend_now();                          // Not expanded for brevity
+
+  try
+  {
+    int total=0;
+    for(size_t n=0; n<10; n++)
     {
-      // 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();
+      std::future<int> &&__temp=async_call();        // Bind to rvalue ref, no moving
+      if(!__temp.await_ready())                      // defaults to __temp.is_ready()
+      {
+        // Internally generated by the compiler to resume me at the resume_me_detached goto label
+        // after storing my state into __context
+        unspecified_callable &&__resume_me(__frame_allocator, __resume_promise, resume_me_detached);
+
+        // Have __temp, when signalled, resume my execution. 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 __return_object;                      // exits function with future, will resume and signal later
+      }
+never_resumed:                                       // This path only taken if function never resumed
+      total+=__temp.await_resume();                  // defaults to __temp.get(), this is always ready and does not block
     }
-never_resumed:                                       // This path only taken if function not resumed
-    total+=__temp.await_resume();                    // defaults to __temp.get()
-  }
-  if(__resume_promise.final_suspend())
+    __context->__resume_promise.set_value(total);
+  }
+  catch(...)
+  {
+    __context->__resume_promise.set_exception(std::current_exception());
+  }
+  if(__context->__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
+  __context->~__context_type();
+  __frame_allocator.deallocate(__context, sizeof(__context_type));
+  return __return_object;
   
 
 
-  // *** 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()
+    // *** ALTERNATIVE DETACHED CODE PATH FOR WHEN THE FUNCTION IS RESUMED ***
+    for(size_t n=0; n<10; n++)
     {
-      // 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();
+      std::future<int> &&__temp=async_call();        // Bind to rvalue ref, no moving
+      if(!__temp.await_ready())                      // defaults to __temp.is_ready()
+      {
+        // Have __temp, when signalled, resume my execution. 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(), this is always ready and does not block
     }
-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
+    __context->__resume_promise.set_value(total);
+  }
+  catch(...)
+  {
+    __context->__resume_promise.set_exception(std::current_exception());
+  }
+  if(__context->__resume_promise.final_suspend())
+    return suspend_now();                            // Not expanded for brevity, jumps to resume_me_addr path
+  __context->~__context_type();
+  __frame_allocator.deallocate(__context, sizeof(__context_type));
   // No meaningful return from this function can occur
 }
@@ -1351 +1379 @@
  }}}
 
- 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.
+ This boilerplate expanded version may still hurt the head, so here is essentially what happens:
+ 1. We dynamically allocate a stack frame on entry, and that dynamic memory allocation sticks around until the resumable function completes.
+ 2. We always construct a promise-future pair for the result (or whatever synchronisation object `coroutine_traits` says) on entry to the function.
+ 3. If `async_call()` always returns a signalled future, we add the result to total, signal the future and return the future.
+ 4. If `async_call()` ever returns an unsignaled future, we ask the unsignaled future to resume our detached path when it is signalled. We suspend ourselves, and return our future immediately. At some point our detached path will signal the future.
+
+ The `await_ready(), await_suspend()` and `await_resume()` functions are firstly looked up as member functions of the synchronisation type returned by the traits specialisation. 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:
@@ -1378 +1410 @@
  }}}
 
- 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.
+ 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. Note that for each iteration, a new promise and future pair is created, then destroyed and created, and so on until the generator returns.
+
+All this is great if you are on Microsoft's compiler, but what about the rest of us before C++ 1z? Luckily [http://olk.github.io/libs/fiber/doc/html/ Boost has a conditionally accepted library called Boost.Fiber] which was one of the C++ 11/14 libraries reviewed above and this, with a few caveats, provides good feature parity with proposed C++1z coroutines. Boost.Fiber provides a mirror image of the STL threading library, so:
+
+|| `std::thread`             || => || `fiber::fiber`              ||
+|| `std::this_thread`        || => || `fiber::this_fiber`         ||
+|| `std::mutex`              || => || `fiber::mutex`              ||
+|| `std::condition_variable` || => || `fiber::condition_variable` ||
+|| `std::future<T>`          || => || `fiber::future<T>`          ||
+
+Rewriting the above example to use Boost.Fiber instead (TODO):
+
+{{{#!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();  // Note the await keyword, this is where the function might suspend
+  return total;
+}
+
+int main(void)
+{
+  std::cout << "Total is " << accumulate().get() << std::endl;
+  return 0;
+}
+}}}
 
 TODO
-
 
 Everything i/o async. Boost.Fiber.