diff options
Diffstat (limited to 'llvm/docs')
| -rw-r--r-- | llvm/docs/ExceptionHandling.rst | 31 | ||||
| -rw-r--r-- | llvm/docs/LangRef.rst | 94 |
2 files changed, 72 insertions, 53 deletions
diff --git a/llvm/docs/ExceptionHandling.rst b/llvm/docs/ExceptionHandling.rst index 87465343dfe..fce875b9b8a 100644 --- a/llvm/docs/ExceptionHandling.rst +++ b/llvm/docs/ExceptionHandling.rst @@ -614,20 +614,19 @@ specifications with one combined instruction. All potentially throwing calls in a ``noexcept`` function should transitively unwind to a terminateblock. Throw specifications are not implemented by MSVC, and are not yet supported. -Each of these new EH pad instructions has a label operand that indicates which +Each of these new EH pad instructions has a way to identify which action should be considered after this action. The ``catchpad`` and -``terminatepad`` instructions are terminators, and this label is considered to -be an unwind destination analogous to the unwind destination of an invoke. The +``terminatepad`` instructions are terminators, and have a label operand considered +to be an unwind destination analogous to the unwind destination of an invoke. The ``cleanuppad`` instruction is different from the other two in that it is not a -terminator, and this label operand is not an edge in the CFG. The code inside a -cleanuppad runs before transferring control to the next action, so the -``cleanupret`` instruction is the instruction that unwinds to the next EH pad. -All of these "unwind edges" may refer to a basic block that contains an EH pad -instruction, or they may simply unwind to the caller. Unwinding to the caller -has roughly the same semantics as the ``resume`` instruction in the -``landingpad`` model. When inlining through an invoke, instructions that unwind -to the caller are hooked up to unwind to the unwind destination of the call -site. +terminator. The code inside a cleanuppad runs before transferring control to the +next action, so the ``cleanupret`` instruction is the instruction that holds a +label operand and unwinds to the next EH pad. All of these "unwind edges" may +refer to a basic block that contains an EH pad instruction, or they may simply +unwind to the caller. Unwinding to the caller has roughly the same semantics as +the ``resume`` instruction in the ``landingpad`` model. When inlining through an +invoke, instructions that unwind to the caller are hooked up to unwind to the +unwind destination of the call site. Putting things together, here is a hypothetical lowering of some C++ that uses all of the new IR instructions: @@ -674,17 +673,17 @@ all of the new IR instructions: ; EH scope code, ordered innermost to outermost: lpad.cleanup: ; preds = %invoke.cont - cleanuppad [label %lpad.catch] + %cleanup = cleanuppad [] call void @"\01??_DCleanup@@QEAA@XZ"(%struct.Cleanup* nonnull %obj) nounwind - cleanupret unwind label %lpad.catch + cleanupret %cleanup unwind label %lpad.catch lpad.catch: ; preds = %entry, %lpad.cleanup - catchpad void [%rtti.TypeDescriptor2* @"\01??_R0H@8", i32 0, i32* %e] + %catch = catchpad [%rtti.TypeDescriptor2* @"\01??_R0H@8", i32 0, i32* %e] to label %catch unwind label %lpad.terminate catch: ; preds = %lpad.catch %9 = load i32, i32* %e, align 4 - catchret label %return + catchret %catch label %return lpad.terminate: terminatepad [void ()* @"\01?terminate@@YAXXZ"] diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst index 8a9ea13de08..9041c0cb206 100644 --- a/llvm/docs/LangRef.rst +++ b/llvm/docs/LangRef.rst @@ -5138,7 +5138,7 @@ Syntax: :: - <resultval> = catchpad <resultty> [<args>*] + <resultval> = catchpad [<args>*] to label <normal label> unwind label <exception label> Overview: @@ -5153,9 +5153,9 @@ routine requires to know if this is an appropriate place to catch the exception. Control is tranfered to the ``exception`` label if the ``catchpad`` is not an appropriate handler for the in-flight exception. The ``normal`` label should contain the code found in the ``catch`` -portion of a ``try``/``catch`` sequence. It defines values supplied by -the :ref:`personality function <personalityfn>` upon re-entry to the -function. The ``resultval`` has the type ``resultty``. +portion of a ``try``/``catch`` sequence. The ``resultval`` has the type +:ref:`token <t_token>` and is used to match the ``catchpad`` to +corresponding :ref:`catchrets <i_catchret>`. Arguments: """""""""" @@ -5170,15 +5170,11 @@ label to transfer control to if it doesn't. Semantics: """""""""" -The '``catchpad``' instruction defines the values which are set by the -:ref:`personality function <personalityfn>` upon re-entry to the function, and -therefore the "result type" of the ``catchpad`` instruction. As with -calling conventions, how the personality function results are -represented in LLVM IR is target specific. - When the call stack is being unwound due to an exception being thrown, the exception is compared against the ``args``. If it doesn't match, then control is transfered to the ``exception`` basic block. +As with calling conventions, how the personality function results are +represented in LLVM IR is target specific. The ``catchpad`` instruction has several restrictions: @@ -5192,11 +5188,14 @@ The ``catchpad`` instruction has several restrictions: catch block. - A basic block that is not a catch block may not include a '``catchpad``' instruction. +- A catch block which has another catch block as a predecessor may not have + any other predecessors. - It is undefined behavior for control to transfer from a ``catchpad`` to a - ``cleanupret`` without first executing a ``catchret`` and a subsequent - ``cleanuppad``. -- It is undefined behavior for control to transfer from a ``catchpad`` to a - ``ret`` without first executing a ``catchret``. + ``ret`` without first executing a ``catchret`` that consumes the + ``catchpad`` or unwinding through its ``catchendpad``. +- It is undefined behavior for control to transfer from a ``catchpad`` to + itself without first executing a ``catchret`` that consumes the + ``catchpad`` or unwinding through its ``catchendpad``. Example: """""""" @@ -5204,7 +5203,7 @@ Example: .. code-block:: llvm ;; A catch block which can catch an integer. - %res = catchpad { i8*, i32 } [i8** @_ZTIi] + %tok = catchpad [i8** @_ZTIi] to label %int.handler unwind label %terminate .. _i_catchendpad: @@ -5264,7 +5263,8 @@ The ``catchendpad`` instruction has several restrictions: '``catchendpad``' instruction. - Exactly one catch block may unwind to a ``catchendpad``. - The unwind target of invokes between a ``catchpad`` and a - corresponding ``catchret`` must be its ``catchendpad``. + corresponding ``catchret`` must be its ``catchendpad`` or + an inner EH pad. Example: """""""" @@ -5284,7 +5284,7 @@ Syntax: :: - catchret <type> <value> to label <normal> + catchret <value> to label <normal> Overview: """"""""" @@ -5296,8 +5296,10 @@ single successor. Arguments: """""""""" -The '``catchret``' instruction requires one argument which specifies -where control will transfer to next. +The first argument to a '``catchret``' indicates which ``catchpad`` it +exits. It must be a :ref:`catchpad <i_catchpad>`. +The second argument to a '``catchret``' specifies where control will +transfer to next. Semantics: """""""""" @@ -5309,13 +5311,21 @@ The :ref:`personality function <personalityfn>` gets a chance to execute arbitrary code to, for example, run a C++ destructor. Control then transfers to ``normal``. It may be passed an optional, personality specific, value. +It is undefined behavior to execute a ``catchret`` whose ``catchpad`` has +not been executed. +It is undefined behavior to execute a ``catchret`` if any ``catchpad`` or +``cleanuppad`` has been executed, without subsequently executing a +corresponding ``catchret``/``cleanupret`` or unwinding out of the inner +pad, following the most recent execution of the ``catchret``'s corresponding +``catchpad``. + Example: """""""" .. code-block:: llvm - catchret label %continue + catchret %catch label %continue .. _i_cleanupret: @@ -5327,8 +5337,8 @@ Syntax: :: - cleanupret <type> <value> unwind label <continue> - cleanupret <type> <value> unwind to caller + cleanupret <value> unwind label <continue> + cleanupret <value> unwind to caller Overview: """"""""" @@ -5340,9 +5350,9 @@ an optional successor. Arguments: """""""""" -The '``cleanupret``' instruction requires one argument, which must have the -same type as the result of any '``cleanuppad``' instruction in the same -function. It also has an optional successor, ``continue``. +The '``cleanupret``' instruction requires one argument, which indicates +which ``cleanuppad`` it exits, and must be a :ref:`cleanuppad <i_cleanuppad>`. +It also has an optional successor, ``continue``. Semantics: """""""""" @@ -5351,14 +5361,21 @@ The '``cleanupret``' instruction indicates to the :ref:`personality function <personalityfn>` that one :ref:`cleanuppad <i_cleanuppad>` it transferred control to has ended. It transfers control to ``continue`` or unwinds out of the function. +It is undefined behavior to execute a ``cleanupret`` whose ``cleanuppad`` has +not been executed. +It is undefined behavior to execute a ``cleanupret`` if any ``catchpad`` or +``cleanuppad`` has been executed, without subsequently executing a +corresponding ``catchret``/``cleanupret`` or unwinding out of the inner pad, +following the most recent execution of the ``cleanupret``'s corresponding +``cleanuppad``. Example: """""""" .. code-block:: llvm - cleanupret void unwind to caller - cleanupret { i8*, i32 } %exn unwind label %continue + cleanupret %cleanup unwind to caller + cleanupret %cleanup unwind label %continue .. _i_terminatepad: @@ -8391,7 +8408,7 @@ Syntax: :: - <resultval> = cleanuppad <resultty> [<args>*] + <resultval> = cleanuppad [<args>*] Overview: """"""""" @@ -8403,7 +8420,8 @@ transfer control to run cleanup actions. The ``args`` correspond to whatever additional information the :ref:`personality function <personalityfn>` requires to execute the cleanup. -The ``resultval`` has the type ``resultty``. +The ``resultval`` has the type :ref:`token <t_token>` and is used to +match the ``cleanuppad`` to corresponding :ref:`cleanuprets <i_cleanupret>`. Arguments: """""""""" @@ -8415,9 +8433,8 @@ Semantics: """""""""" The '``cleanuppad``' instruction defines the values which are set by the -:ref:`personality function <personalityfn>` upon re-entry to the function, and -therefore the "result type" of the ``cleanuppad`` instruction. As with -calling conventions, how the personality function results are +:ref:`personality function <personalityfn>` upon re-entry to the function. +As with calling conventions, how the personality function results are represented in LLVM IR is target specific. When the call stack is being unwound due to an exception being thrown, @@ -8434,18 +8451,21 @@ The ``cleanuppad`` instruction has several restrictions: cleanup block. - A basic block that is not a cleanup block may not include a '``cleanuppad``' instruction. +- All ``cleanupret``s which exit a cleanuppad must have the same + exceptional successor. - It is undefined behavior for control to transfer from a ``cleanuppad`` to a - ``catchret`` without first executing a ``cleanupret`` and a subsequent - ``catchpad``. -- It is undefined behavior for control to transfer from a ``cleanuppad`` to a - ``ret`` without first executing a ``cleanupret``. + ``ret`` without first executing a ``cleanupret`` that consumes the + ``cleanuppad`` or unwinding out of the ``cleanuppad``. +- It is undefined behavior for control to transfer from a ``cleanuppad`` to + itself without first executing a ``cleanupret`` that consumes the + ``cleanuppad`` or unwinding out of the ``cleanuppad``. Example: """""""" .. code-block:: llvm - %res = cleanuppad { i8*, i32 } [label %nextaction] + %tok = cleanuppad [] .. _intrinsics: |
