[C++ coroutines 5/6] Standard library header.

[Jonathan Wakely]

On 17/11/19 10:27 +0000, Iain Sandoe wrote:
>This provides the interfaces mandated by the standard and implements
>the interaction with the coroutine frame by means of inline use of
>builtins expanded at compile-time.  There should be a 1:1 correspondence
>with the standard sections which are cross-referenced.
>
>There is no runtime content.
>
>At this stage we have the content in an inline namespace "n4835" for
>the current CD.
>
>libstdc++-v3/ChangeLog:
>
>2019-11-17  Iain Sandoe  <iain@sandoe.co.uk>
>
>	* include/Makefile.am: Add coroutine to the experimental set.
>	* include/Makefile.in: Regnerated.

"Regnerated" typo.

>	* include/experimental/coroutine: New file.
>---
> libstdc++-v3/include/Makefile.am            |   1 +
> libstdc++-v3/include/Makefile.in            |   1 +
> libstdc++-v3/include/experimental/coroutine | 268 ++++++++++++++++++++++++++++
> 3 files changed, 270 insertions(+)
> create mode 100644 libstdc++-v3/include/experimental/coroutine
>
>diff --git a/libstdc++-v3/include/Makefile.am b/libstdc++-v3/include/Makefile.am
>index 49fd413..4ffe209 100644
>--- a/libstdc++-v3/include/Makefile.am
>+++ b/libstdc++-v3/include/Makefile.am
>@@ -708,6 +708,7 @@ experimental_headers = \
> 	${experimental_srcdir}/array \
> 	${experimental_srcdir}/buffer \
> 	${experimental_srcdir}/chrono \
>+	${experimental_srcdir}/coroutine \

The experimental dir is (currently) only used for TS headers. All
C++20 support is currently experimental, so adding <coroutines> where
<concepts> and <ranges> have been added would be OK.

But I'm not really clear if this is an implementation of the TS or the
C++20 feature.  If it's a hybrid, putting it in
<experimental/coroutines> is fine.

When the final <coroutines> header is added it will need to be in
libsupc++ so that it's included for freestanding builds (and at that
point it won't be able to use <bits/stl_function.h>, but that will be
OK as the final header will be C++20-only and can rely on <compare>
unconditionally, which is also freestanding).

> 	${experimental_srcdir}/deque \
> 	${experimental_srcdir}/executor \
> 	${experimental_srcdir}/forward_list \


>diff --git a/libstdc++-v3/include/experimental/coroutine b/libstdc++-v3/include/experimental/coroutine
>new file mode 100644
>index 0000000..d903352
>--- /dev/null
>+++ b/libstdc++-v3/include/experimental/coroutine
>@@ -0,0 +1,268 @@
>+// <experimental/coroutine> -*- C++ -*-
>+
>+// Copyright (C) 2019 Free Software Foundation, Inc.
>+//
>+// This file is part of the GNU ISO C++ Library.  This library is free
>+// software; you can redistribute it and/or modify it under the
>+// terms of the GNU General Public License as published by the
>+// Free Software Foundation; either version 3, or (at your option)
>+// any later version.
>+
>+// This library is distributed in the hope that it will be useful,
>+// but WITHOUT ANY WARRANTY; without even the implied warranty of
>+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
>+// GNU General Public License for more details.
>+
>+// Under Section 7 of GPL version 3, you are granted additional
>+// permissions described in the GCC Runtime Library Exception, version
>+// 3.1, as published by the Free Software Foundation.
>+
>+// You should have received a copy of the GNU General Public License and
>+// a copy of the GCC Runtime Library Exception along with this program;
>+// see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
>+// <http://www.gnu.org/licenses/>.
>+
>+/** @file experimental/coroutine
>+ *  This is an experimental C++ Library header against the C++20 CD n4835.
>+ *  @ingroup coroutine-ts

The coroutine-ts doc group should be defined somewhere.

>+ */
>+
>+#ifndef _GLIBCXX_EXPERIMENTAL_COROUTINE
>+#define _GLIBCXX_EXPERIMENTAL_COROUTINE 1
>+
>+#pragma GCC system_header
>+
>+// It is very likely that earlier versions would work, but they are untested.
>+#if __cplusplus >= 201402L
>+
>+#include <bits/c++config.h>
>+
>+#if __cplusplus > 201703L && __cpp_impl_three_way_comparison >= 201907L
>+#  include <compare>
>+#  define THE_SPACESHIP_HAS_LANDED 1

This is in trunk now, although not supported by Clang, and not
supported by GCC pre-C++20, so the fallback is OK.

The macro name should be a reserved name though, e.g.
_THE_SPACESHIP_HAS_LANDED

>+#else
>+#  include <bits/stl_function.h>
>+#  define THE_SPACESHIP_HAS_LANDED 0
>+#endif
>+
>+namespace std _GLIBCXX_VISIBILITY (default)
>+{
>+  _GLIBCXX_BEGIN_NAMESPACE_VERSION
>+
>+#if __cpp_coroutines
>+
>+  namespace experimental {
>+  inline namespace coroutines_n4835 {

This should be a reserved name too, e.g. __coroutines_n4835.

>+
>+  // [coroutine.traits]
>+  // [coroutine.traits.primary]
>+  // 17.12.2 coroutine traits
>+  template <typename _R, typename...> struct coroutine_traits
>+  {
>+    using promise_type = typename _R::promise_type;
>+  };
>+
>+  // 17.12.3 Class template coroutine_handle
>+  // [coroutine.handle]
>+  template <typename _Promise = void> struct coroutine_handle;
>+
>+  template <> struct coroutine_handle<void>
>+  {
>+  public:
>+    // 17.12.3.1, construct/reset
>+    constexpr coroutine_handle () noexcept : __fr_ptr (0) {}

The libstdc++ naming convention is _M_xxx for non-static members (both
data members and member functions) and _S_xxx for static members
(again, both data member and functions).

This helps to distinguish members from other uglified names like
function parameters and local variables.