llvm-capstone/clang/docs
Chuanqi Xu b7b5907b56
[Coroutines] Introduce [[clang::coro_only_destroy_when_complete]] (#71014)
Close https://github.com/llvm/llvm-project/issues/56980.

This patch tries to introduce a light-weight optimization attribute for
coroutines which are guaranteed to only be destroyed after it reached
the final suspend.

The rationale behind the patch is simple. See the example:

```C++
A foo() {
  dtor d;
  co_await something();
  dtor d1;
  co_await something();
  dtor d2;
  co_return 43;
}
```

Generally the generated .destroy function may be:

```C++
void foo.destroy(foo.Frame *frame) {
  switch(frame->suspend_index()) {
    case 1:
      frame->d.~dtor();
      break;
    case 2:
      frame->d.~dtor();
      frame->d1.~dtor();
      break;
    case 3:
      frame->d.~dtor();
      frame->d1.~dtor();
      frame->d2.~dtor();
      break;
    default: // coroutine completed or haven't started
      break;
  }

  frame->promise.~promise_type();
  delete frame;
}
```

Since the compiler need to be ready for all the cases that the coroutine
may be destroyed in a valid state.

However, from the user's perspective, we can understand that certain
coroutine types may only be destroyed after it reached to the final
suspend point. And we need a method to teach the compiler about this.
Then this is the patch. After the compiler recognized that the
coroutines can only be destroyed after complete, it can optimize the
above example to:

```C++
void foo.destroy(foo.Frame *frame) {
  frame->promise.~promise_type();
  delete frame;
}
```

I spent a lot of time experimenting and experiencing this in the
downstream. The numbers are really good. In a real-world coroutine-heavy
workload, the size of the build dir (including .o files) reduces 14%.
And the size of final libraries (excluding the .o files) reduces 8% in
Debug mode and 1% in Release mode.
2023-11-09 14:42:07 +08:00
..
analyzer [analyzer][clangsa] Add new option to alpha.security.cert.InvalidPtrChecker (#67663) 2023-10-24 13:59:54 +02:00
CommandGuide Add -fkeep-system-includes modifier for -E 2023-10-06 12:55:48 -07:00
DataFlowAnalysisIntroImages
HLSL [Docs] [HLSL] Add note about PCH support 2022-10-07 10:49:21 -07:00
tools [clang-format] Add space in placement new expression 2023-10-20 03:16:28 -07:00
AddressSanitizer.rst [Sanitizer][Docs] Reformat CMake invocation in docs 2023-10-09 22:45:34 +00:00
AMDGPUSupport.rst [amdgpu] start documenting amdgpu support by clang 2023-07-07 10:35:34 -04:00
APINotes.rst
AutomaticReferenceCounting.rst [clang] Fix typos in documentation 2023-05-12 23:19:17 -07:00
Block-ABI-Apple.rst
BlockLanguageSpec.rst
ClangCheck.rst
ClangFormat.rst [clang-format][NFC] Fix broken dump_format_help.py and sync RST file (#65429) 2023-09-07 00:43:19 -07:00
ClangFormatStyleOptions.rst [clang-format] Fix the version for a newly added option 2023-10-25 05:45:32 -07:00
ClangFormattedStatus.rst [RemarkUtil] Refactor llvm-remarkutil to include size-diff 2023-08-02 10:33:18 +01:00
ClangLinkerWrapper.rst [clang][NFC] Remove trailing whitespaces and enforce it in lib, include and docs 2023-06-26 09:34:36 -07:00
ClangOffloadBundler.rst Reland "[HIP] Support compressing device binary" 2023-10-05 11:20:46 -04:00
ClangOffloadPackager.rst [Clang][Docs] Fix typo in clang-offload-packager documentation 2023-09-11 16:24:37 -07:00
ClangPlugins.rst
ClangRepl_design.png [clang-repl] Add basic documentation about clang-repl 2022-11-30 12:30:33 +00:00
ClangRepl.rst Reland "Add Documentation for Execution Results Handling in Clang-Repl (#65650)" 2023-10-24 14:43:00 +00:00
ClangStaticAnalyzer.rst
ClangTools.rst
ClangTransformerTutorial.rst [clang][NFC] Remove trailing whitespaces and enforce it in lib, include and docs 2023-06-26 09:34:36 -07:00
CMakeLists.txt Revert "Add Documentation for Execution Results Handling in Clang-Repl (#65650)" 2023-10-13 09:39:00 +02:00
CodeOwners.rst Update the clang and clang-tools-extra code owners files 2022-09-06 08:28:03 -04:00
conf.py Reland "Add Documentation for Execution Results Handling in Clang-Repl (#65650)" 2023-10-24 14:43:00 +00:00
ConstantInterpreter.rst [documentation] Fix some typos 2023-03-30 15:58:02 +01:00
ControlFlowIntegrity.rst -fsanitize=function: support C 2023-05-22 10:11:30 -07:00
ControlFlowIntegrityDesign.rst
CrossCompilation.rst [documentation] Fix some typos 2023-03-30 15:58:02 +01:00
DataFlowAnalysisIntro.md [documentation] Fix some typos 2023-03-30 15:58:02 +01:00
DataFlowSanitizer.rst [clang] Fix typos in documentation 2023-05-12 23:19:17 -07:00
DataFlowSanitizerDesign.rst Fix duplicate word typos; NFC 2022-11-08 07:21:23 -05:00
DebuggingCoroutines.rst Fx typos in documentation 2023-08-18 23:36:04 -07:00
doxygen-mainpage.dox
doxygen.cfg.in [docs] Hide collaboration and include graphs in doxygen docs 2023-05-04 12:26:51 +02:00
DriverArchitecture.png
DriverInternals.rst
ExternalClangExamples.rst [clang][NFC] Remove trailing whitespaces and enforce it in lib, include and docs 2023-06-26 09:34:36 -07:00
FAQ.rst
HardwareAssistedAddressSanitizerDesign.rst
HIPSupport.rst [HIP] Document func ptr and virtual func (#68126) 2023-10-18 14:14:04 -04:00
HowToSetupToolingForLLVM.rst [AST] Only dump desugared type when visibly different (#65214) 2023-10-26 19:28:28 +01:00
index.rst Fix the Clang sphinx bot 2023-07-25 11:23:36 -04:00
InternalsManual.rst [Driver] Refactor to use llvm Option's new Visibility flags 2023-08-15 14:26:40 -07:00
IntroductionToTheClangAST.rst
ItaniumMangleAbiTags.rst
JSONCompilationDatabase.rst [clang][NFC] Remove trailing whitespaces and enforce it in lib, include and docs 2023-06-26 09:34:36 -07:00
LanguageExtensions.rst [Clang] Add __builtin_vectorelements to get number of elements in vector (#69010) 2023-10-19 10:45:08 +02:00
LeakSanitizer.rst
LibASTImporter.rst
LibASTMatchers.rst
LibASTMatchersReference.html [ASTMatchers] Bring comments & docs back in sync 2023-09-04 13:42:29 +02:00
LibASTMatchersTutorial.rst
LibClang.rst Add libClang guide 2023-07-10 11:15:48 -04:00
LibFormat.rst
LibTooling.rst
LTOVisibility.rst
make.bat
MatrixTypes.rst [C23] Update user-facing docs for C23 2023-08-10 14:19:41 -04:00
MemorySanitizer.rst
MisExpect.rst [clang][NFC] Remove trailing whitespaces and enforce it in lib, include and docs 2023-06-26 09:34:36 -07:00
Modules.rst [clang][modules] Add a c23 module feature 2023-08-29 11:11:14 -07:00
MSVCCompatibility.rst
Multilib.rst [docs] Add missing label 2023-06-14 13:08:07 +01:00
ObjectiveCLiterals.rst
OffloadingDesign.rst [OpenMP][OMPIRBuilder] Rename IsEmbedded and IsTargetCodegen flags 2023-07-10 14:14:16 +01:00
OpenCLSupport.rst Fx typos in documentation 2023-08-18 23:36:04 -07:00
OpenMPSupport.rst [Clang][NFC] Fix sphinx documentation 2023-09-29 00:22:58 -07:00
PCHInternals.rst
PCHLayout.graffle
PCHLayout.png
RAVFrontendAction.rst
README.txt
RefactoringEngine.rst
ReleaseNotes.rst [Coroutines] Introduce [[clang::coro_only_destroy_when_complete]] (#71014) 2023-11-09 14:42:07 +08:00
SafeStack.rst
SanitizerCoverage.rst Fix the clang Sphinx bot 2022-09-16 07:19:30 -04:00
SanitizerSpecialCaseList.rst [SpecialCaseList] Add option to use Globs instead of Regex to match patterns 2023-09-01 09:06:11 -07:00
SanitizerStats.rst
ShadowCallStack.rst [CodeGen][RISCV] Change Shadow Call Stack Register to X3 2023-04-12 21:06:22 +00:00
SourceBasedCodeCoverage.rst [clang][NFC] Remove trailing whitespaces and enforce it in lib, include and docs 2023-06-26 09:34:36 -07:00
StandardCPlusPlusModules.rst [docs] [C++20] [Modules] Add document for the case of duplicated '-fmodule-file=<module-name>=' 2023-10-30 11:25:21 +08:00
SYCLSupport.rst [clang][doc] Fix link to SYCL compiler design doc 2023-03-28 18:09:52 +02:00
ThinLTO.rst [clang][docs] Document ThinLTO options for ld64.lld 2023-02-21 12:09:27 -05:00
ThreadSafetyAnalysis.rst Thread safety analysis: Support copy-elided production of scoped capabilities through arbitrary calls 2022-10-13 19:36:15 +02:00
ThreadSanitizer.rst
Toolchain.rst
Tooling.rst
UndefinedBehaviorSanitizer.rst [clang][NFC] Remove trailing whitespaces and enforce it in lib, include and docs 2023-06-26 09:34:36 -07:00
UsersManual.rst [ItaniumCXXABI] Add -fassume-nothrow-exception-dtor to assume that all exception objects' destructors are non-throwing 2023-11-05 00:39:38 -07:00

See llvm/docs/README.txt