Deprecate experimental coroutine headers (#5804)

Author: StephanTLavavej

stl/inc/coroutine

@@ -9,12 +9,10 @@
 #if _STL_COMPILER_PREPROCESSOR
 
 #ifdef _RESUMABLE_FUNCTIONS_SUPPORTED
-_EMIT_STL_WARNING(STL4039, "The contents of <coroutine> are not available with /await. "
-                           "Remove /await or use /await:strict for standard coroutines. "
-                           "Use <experimental/coroutine> for legacy /await support.");
-#else // ^^^ /await / no /await vvv
-#ifndef __cpp_lib_coroutine
-_EMIT_STL_WARNING(STL4038, "The contents of <coroutine> are available only with C++20 or later or /await:strict.");
+_EMIT_STL_WARNING(STL4039, "The <coroutine> header is incompatible with the deprecated /await compiler option.");
+#elif !defined(__cpp_lib_coroutine)
+_EMIT_STL_WARNING(STL4038, "The contents of <coroutine> are available only with C++20 or later "
+                           "(or /await:strict in C++14/17).");
 #else // ^^^ <coroutine> is not available / <coroutine> is available vvv
 #ifndef _ALLOW_COROUTINE_ABI_MISMATCH
 #pragma detect_mismatch("_COROUTINE_ABI", "2")
@@ -270,7 +268,6 @@ _STL_RESTORE_CLANG_WARNINGS
 #pragma warning(pop)
 #pragma pack(pop)
 
-#endif // ^^^ defined(__cpp_lib_coroutine) ^^^
-#endif // ^^^ !defined(_RESUMABLE_FUNCTIONS_SUPPORTED) ^^^
+#endif // ^^^ <coroutine> is available ^^^
 #endif // _STL_COMPILER_PREPROCESSOR
 #endif // _COROUTINE_

stl/inc/experimental/coroutine

@@ -25,15 +25,19 @@ _STL_DISABLE_CLANG_WARNINGS
 #pragma push_macro("new")
 #undef new
 
-#if defined(__clang__) && !defined(_SILENCE_CLANG_COROUTINE_MESSAGE)
-#error The <experimental/coroutine>, <experimental/generator>, and <experimental/resumable> \
-headers do not support Clang, but the C++20 <coroutine> header does.
-#endif // defined(__clang__) && !defined(_SILENCE_CLANG_COROUTINE_MESSAGE)
-
-#ifdef __cpp_impl_coroutine
-#error The <experimental/coroutine> and <experimental/resumable> headers are only supported with \
-/await and implement pre-C++20 coroutine support. Use <coroutine> for standard C++20 coroutines.
-#endif // defined(__cpp_impl_coroutine)
+#ifdef __clang__
+_EMIT_STL_ERROR(STL1009, "The <experimental/coroutine>, <experimental/generator>, and <experimental/resumable> "
+                         "headers do not support Clang, but the C++20 <coroutine> and C++23 <generator> headers do.");
+#elif defined(__cpp_impl_coroutine)
+_EMIT_STL_ERROR(STL1010, "You're compiling with support for standard C++20 coroutines "
+                         "(also available with /await:strict in C++14/17), so you should include <coroutine> "
+                         "instead of <experimental/coroutine> and <experimental/resumable>.");
+#elif !defined(_SILENCE_EXPERIMENTAL_COROUTINE_DEPRECATION_WARNINGS)
+_EMIT_STL_ERROR(STL1011, "The /await compiler option, <experimental/coroutine>, <experimental/generator>, and "
+                         "<experimental/resumable> are deprecated by Microsoft and will be REMOVED SOON. "
+                         "They are superseded by the C++20 <coroutine> and C++23 <generator> headers. You can define "
+                         "_SILENCE_EXPERIMENTAL_COROUTINE_DEPRECATION_WARNINGS to suppress this error for now.");
+#endif // _SILENCE_EXPERIMENTAL_COROUTINE_DEPRECATION_WARNINGS
 
 // intrinsics used in implementation of coroutine_handle
 extern "C" size_t _coro_resume(void*) noexcept;

stl/inc/experimental/generator

@@ -13,12 +13,23 @@
 #endif
 #include <memory>
 
-#if defined(__cpp_impl_coroutine)
+#ifdef __clang__
+_EMIT_STL_ERROR(STL1009, "The <experimental/coroutine>, <experimental/generator>, and <experimental/resumable> "
+                         "headers do not support Clang, but the C++20 <coroutine> and C++23 <generator> headers do.");
+#elif !defined(_SILENCE_EXPERIMENTAL_COROUTINE_DEPRECATION_WARNINGS)
+_EMIT_STL_ERROR(STL1011, "The /await compiler option, <experimental/coroutine>, <experimental/generator>, and "
+                         "<experimental/resumable> are deprecated by Microsoft and will be REMOVED SOON. "
+                         "They are superseded by the C++20 <coroutine> and C++23 <generator> headers. You can define "
+                         "_SILENCE_EXPERIMENTAL_COROUTINE_DEPRECATION_WARNINGS to suppress this error for now.");
+#elif defined(__cpp_impl_coroutine)
 #include <coroutine>
 #elif defined(__cpp_coroutines)
 #include <experimental/resumable>
 #else // ^^^ legacy coroutines / no coroutine support vvv
-#error <experimental/generator> requires /std:c++latest or /await compiler options
+_EMIT_STL_ERROR(STL1012, "You've included the <experimental/generator> header without compiler support for "
+                         "legacy coroutines (available with the deprecated /await compiler option) or "
+                         "standard C++20 coroutines (also available with /await:strict in C++14/17). "
+                         "You should include C++23 <generator> instead of <experimental/generator>.");
 #endif // ^^^ no coroutine support ^^^
 
 #pragma pack(push, _CRT_PACKING)

stl/inc/yvals_core.h

@@ -1521,7 +1521,7 @@ _EMIT_STL_ERROR(STL1004, "C++98 unexpected() is incompatible with C++23 unexpect
 
 // next warning number: STL4049
 
-// next error number: STL1009
+// next error number: STL1013
 
 // P0619R4 Removing C++17-Deprecated Features
 #ifndef _HAS_FEATURES_REMOVED_IN_CXX20

tests/std/tests/VSO_0971246_legacy_await_headers/test.cpp

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
+#define _SILENCE_EXPERIMENTAL_COROUTINE_DEPRECATION_WARNINGS
+
 #include <cstdio>
 #include <experimental/generator>
 #include <future>