[docs] Update the status for coroutines

[ChuanqiXu]

Summary

According to the discussion in https://discourse.llvm.org/t/rfc-could-we-mark-coroutines-as-unreleased-now/69220

We should mark coroutines as "it’s supported fully everywhere but on Windows targets".

[aaron.ballman]

Should we also be updating InitPreprocessor.cpp at the same time, for non-Windows targets? I see we define:

// TS features.
if (LangOpts.Coroutines)
  Builder.defineMacro("__cpp_coroutines", "201703L");

but we don't define __cpp_­impl_­coroutine: http://eel.is/c++draft/tab:cpp.predefined.ft

And this should definitely come with a release note so users know about the change in status.

clang/www/cxx_status.html

1225–1226

[ChuanqiXu]

Address comments.

[ChuanqiXu]

but we don't define __cpp_­impl_­coroutine: http://eel.is/c++draft/tab:cpp.predefined.ft

We defined __cpp_­impl_­coroutine. And __cpp_coroutines is for Coroutines TS. I forgot to remove this too. I'll handle it in a separate patch.

[ChuanqiXu]

Should we also be updating InitPreprocessor.cpp at the same time, for non-Windows targets?

I didn't address this since we didn't do this before. (Defining feature macro according to the targets).

Also I feel it may be bad for windows users. Since currently the coroutines on windows is not completely broken. It is still workable in some (or a lot?) situations. It is just out of maintenance.

[aaron.ballman]

In D146187#4201223, @ChuanqiXu wrote:

but we don't define __cpp_­impl_­coroutine: http://eel.is/c++draft/tab:cpp.predefined.ft

We defined __cpp_­impl_­coroutine. And __cpp_coroutines is for Coroutines TS. I forgot to remove this too. I'll handle it in a separate patch.

Thanks for handling the TS bits, but what am I misunderstanding here: https://godbolt.org/z/KdrM713r5 ?

[cor3ntin]

In D146187#4201905, @aaron.ballman wrote:

In D146187#4201223, @ChuanqiXu wrote:

but we don't define __cpp_­impl_­coroutine: http://eel.is/c++draft/tab:cpp.predefined.ft

We defined __cpp_­impl_­coroutine. And __cpp_coroutines is for Coroutines TS. I forgot to remove this too. I'll handle it in a separate patch.

Thanks for handling the TS bits, but what am I misunderstanding here: https://godbolt.org/z/KdrM713r5 ?

Hahaha.
For some reason - i should ask why to Tim Song one day - the html version of the standard has weird injected non breaking spaces after underscores, you got bit by that
https://godbolt.org/z/1ceKfbTPc

[aaron.ballman]

In D146187#4201271, @ChuanqiXu wrote:

Should we also be updating InitPreprocessor.cpp at the same time, for non-Windows targets?

I didn't address this since we didn't do this before. (Defining feature macro according to the targets).

Also I feel it may be bad for windows users. Since currently the coroutines on windows is not completely broken. It is still workable in some (or a lot?) situations. It is just out of maintenance.

The problem is, "out of maintenance" basically means "not supported" as far as users are concerned when they run into these bugs. I don't think we should claim to support the feature on a target where we know it has significant issues. I think in general we want feature testing macros to be treated as our signal to the user that we think something is complete, not that we think something is in progress but pretty usable.

[aaron.ballman]

In D146187#4201910, @cor3ntin wrote:

In D146187#4201905, @aaron.ballman wrote:

In D146187#4201223, @ChuanqiXu wrote:

but we don't define __cpp_­impl_­coroutine: http://eel.is/c++draft/tab:cpp.predefined.ft

We defined __cpp_­impl_­coroutine. And __cpp_coroutines is for Coroutines TS. I forgot to remove this too. I'll handle it in a separate patch.

Thanks for handling the TS bits, but what am I misunderstanding here: https://godbolt.org/z/KdrM713r5 ?

Hahaha.
For some reason - i should ask why to Tim Song one day - the html version of the standard has weird injected non breaking spaces after underscores, you got bit by that
https://godbolt.org/z/1ceKfbTPc

😱😱😱

Wow, thank you, that was not something I'd have figured out on my own for quite a while!

Ugh, that does sort of change the calculus for whether we do or don't claim support on Windows. If removing the definition of that macro on Windows causes significant code breakage, that would be a reason we should leave it defined. But do we have evidence of that?

[bruno]

... I think in general we want feature testing macros to be treated as our signal to the user that we think something is complete, not that we think something is in progress but pretty usable.

+1

[ChuanqiXu]

Ugh, that does sort of change the calculus for whether we do or don't claim support on Windows. If removing the definition of that macro on Windows causes significant code breakage, that would be a reason we should leave it defined. But do we have evidence of that?

Ah, yes. This is what I want to say. Simply, if we remove the definition for __cpp_impl_coroutines, the coroutine header in MS/STL and libstdc++ can't work anymore. For libstdc++, all the coroutine things are only defined if __cpp_impl_coroutines is defined (https://github.com/gcc-mirror/gcc/blob/master/libstdc%2B%2B-v3/include/std/coroutine#L58-L69). And this is the same for MS/STL: https://github.com/microsoft/STL/blob/5116678ea11245b232a6e43824aad25fb60b9c6e/stl/inc/yvals_core.h#L1587-L1589 and https://github.com/microsoft/STL/blob/be29af22c049774ae93f2c33e4eb5d801e12216c/stl/inc/coroutine#L17-L39. So I can image that many uses of coroutines in Windows may get useless after we undefined the __cpp_impl_coroutines macros.

[aaron.ballman]

In D146187#4205271, @ChuanqiXu wrote:

Ugh, that does sort of change the calculus for whether we do or don't claim support on Windows. If removing the definition of that macro on Windows causes significant code breakage, that would be a reason we should leave it defined. But do we have evidence of that?

Ah, yes. This is what I want to say. Simply, if we remove the definition for __cpp_impl_coroutines, the coroutine header in MS/STL and libstdc++ can't work anymore. For libstdc++, all the coroutine things are only defined if __cpp_impl_coroutines is defined (https://github.com/gcc-mirror/gcc/blob/master/libstdc%2B%2B-v3/include/std/coroutine#L58-L69). And this is the same for MS/STL: https://github.com/microsoft/STL/blob/5116678ea11245b232a6e43824aad25fb60b9c6e/stl/inc/yvals_core.h#L1587-L1589 and https://github.com/microsoft/STL/blob/be29af22c049774ae93f2c33e4eb5d801e12216c/stl/inc/coroutine#L17-L39. So I can image that many uses of coroutines in Windows may get useless after we undefined the __cpp_impl_coroutines macros.

Okay, that pretty much paints us into a corner, I guess. If we don't define it any longer, we break existing (working) uses of the feature on Windows, but we defined it prematurely. In this case, let's leave the macro defined so we don't break existing uses -- in the future, I think we should be more conservative with defining feature test macros.

[aaron.ballman]

LGTM, thank you!

[ChuanqiXu]

Okay, that pretty much paints us into a corner, I guess. If we don't define it any longer, we break existing (working) uses of the feature on Windows, but we defined it prematurely. In this case, let's leave the macro defined so we don't break existing uses -- in the future, I think we should be more conservative with defining feature test macros.

Totally agreed. Thanks for your reviewing!

clang/docs/ReleaseNotes.rst

 
 C++20 Feature Support
 ^^^^^^^^^^^^^^^^^^^^^
 - Support for out-of-line definitions of constrained templates has been improved.
   This partially fixes `#49620 <https://github.com/llvm/llvm-project/issues/49620>`_.
 - Lambda templates with a requires clause directly after the template parameters now parse
   correctly if the requires clause consists of a variable with a dependent type.
   (`#61278 <https://github.com/llvm/llvm-project/issues/61278>`_)
+- Announced C++20 Coroutines is fully supported on all targets except Windows, which
+  still has some stability and ABI issues.
 
 C++2b Feature Support
 ^^^^^^^^^^^^^^^^^^^^^
 
 - Implemented `P2036R3: Change scope of lambda trailing-return-type <https://wg21.link/P2036R3>`_
   and `P2579R0 Mitigation strategies for P2036 <https://wg21.link/P2579R0>`_.
   These proposals modify how variables captured in lambdas can appear in trailing return type
   expressions and how their types are deduced therein, in all C++ language versions.

clang/www/cxx_status.html

</tr>
         <td><a href="https://wg21.link/P2788R0">P2788R0</a> (<a href="#dr">DR</a>)</td>
         <td class="none" align="center">No</td>
       </tr>
     <tr>
       <td>Coroutines</td>
       <td><a href="https://wg21.link/p0912r5">P0912R5</a></td>
       <td class="partial" align="center">
         <details><summary>Partial</summary>
-          The optimizer does not yet handle TLS with
-  <tt>__attribute__((const))</tt> attribute correctly. There can be issues where the
-  coroutine may resume on a different thread. <br \>This feature requires further
-  analysis of the C++ Standard to determine what work is necessary for conformance.
+          Fully supported on all targets except Windows, which
+          still has some stability and ABI issues.
         </details></td>
     </tr>
     <!-- Cologne 2019 papers -->
     <tr>
       <td>Deprecate <tt>a[b,c]</tt></td>
       <td><a href="https://wg21.link/p1161r3">P1161R3</a></td>
       <td class="full" align="center">Clang 9</td>
     </tr>