================ @@ -0,0 +1,266 @@ +======================================== +LLVM IR Generation for EH and Cleanups +======================================== + +.. contents:: + :local: + +Overview +======== + +This document describes how Clang's LLVM IR generation represents exception +handling (EH) and C++ cleanups. It focuses on the data structures and control +flow patterns used to model normal and exceptional exits, and it outlines how +the generated IR differs across common ABI models. + +Core Model +========== + +EH and cleanup handling is centered around an ``EHScopeStack`` that records +nested scopes for: + +- **Cleanups**, which run on normal control flow, exceptional control flow, or + both. These are used for destructors, full-expression cleanups, and other + scope-exit actions. +- **Catch scopes**, which represent ``try``/``catch`` handlers. +- **Filter scopes**, used to model dynamic exception specifications and some + platform-specific filters. +- **Terminate scopes**, used for ``noexcept`` and similar termination paths. + +Each cleanup is a small object with an ``Emit`` method. When a cleanup scope is +popped, the IR generator decides whether it must materialize a normal cleanup +block (for fallthrough, branch-through, or unresolved ``goto`` fixups) and/or an +EH cleanup entry (when exceptional control flow can reach the cleanup). This +results in a flattened CFG where cleanup lifetime is represented by the blocks +and edges that flow into those blocks. + +Key Components +============== + +The LLVM IR generation for EH and cleanups is spread across several core +components: + +- ``CodeGenModule`` owns module-wide state such as the LLVM module, target + information, and the selected EH personality function. It provides access to + ABI helpers via ``CGCXXABI`` and target-specific hooks. +- ``CodeGenFunction`` manages per-function state and IR building. It owns the + ``EHScopeStack``, tracks the current insertion point, and emits blocks, calls, + and branches. Most cleanup and EH control flow is built here. +- ``EHScopeStack`` is the central stack of scopes used to model EH and cleanup + semantics. It stores ``EHCleanupScope`` entries for cleanups, along with + ``EHCatchScope``, ``EHFilterScope``, and ``EHTerminateScope`` for handlers and + termination logic. +- ``EHCleanupScope`` stores the cleanup object plus state data (active flags, + fixup depth, and enclosing scope links). When a cleanup scope is popped, + ``CodeGenFunction`` decides whether to emit a normal cleanup block, an EH + cleanup entry, or both. +- Cleanup emission helpers implement the mechanics of branching through + cleanups, threading fixups, and emitting cleanup blocks. +- Exception emission helpers implement landing pads, dispatch blocks, + personality selection, and helper routines for try/catch, filters, and + terminate handling. +- ``CGCXXABI`` (and its ABI-specific implementations such as + ``ItaniumCXXABI`` and ``MicrosoftCXXABI``) provide ABI-specific lowering for + throws, catch handling, and destructor emission details. +- C++ expression, class, and statement emission logic drives construction and + destruction, and is responsible for pushing/popping cleanups in response to + AST constructs. + +These components interact along a consistent pattern: AST traversal in +``CodeGenFunction`` emits code and pushes cleanups or EH scopes; ``EHScopeStack`` +records scope nesting; cleanup and exception helpers materialize the CFG as +scopes are popped; and ``CGCXXABI`` supplies ABI-specific details for landing +pads or funclets. + +Normal Cleanups and Branch Fixups +================================= + +Normal control flow exits (``return``, ``break``, ``goto``, fallthrough, etc.) +are threaded through cleanups by creating explicit cleanup blocks. The +implementation supports unresolved branches to labels by emitting an optimistic +branch and recording a fixup. When a cleanup is popped, fixups are threaded +through the cleanup by turning that optimistic branch into a switch that +dispatches to the correct destination after the cleanup runs. + +Cleanups use a switch on an internal "cleanup destination" slot even for simple +source constructs. It is a general mechanism that allows multiple exits to share +the same cleanup code while still reaching the correct final destination. + +Exceptional Cleanups and EH Dispatch +==================================== + +Exceptional exits (``throw``, ``invoke`` unwinds) are routed through EH cleanup +entries, which are reached via a landing pad or a funclet dispatch block, +depending on the target ABI. + +For Itanium-style EH (such as is used on x86-64 Linux), the IR uses ``invoke`` +to call potentially-throwing operations and a ``landingpad`` instruction to +capture the exception and selector values. The landing pad aggregates the +in-scope catch, filter, and cleanup clauses, then branches to a dispatch block ---------------- andykaylor wrote:
Hmm. We shouldn't be talking about filters here, because that's Windows-specific (though we do have handling for it in `emitLandingPad`, so I could be wrong), but I believe otherwise this is trying to describe the way that control flow is routed from the landing pad block to the cleanup and catch blocks that apply to the EH scope we were in when the invoke statement that led to the landing pad was emitted. https://github.com/llvm/llvm-project/pull/176236 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
