!2 = !{ i8 0, i8 2, i8 3, i8 6 }
!3 = !{ i8 -2, i8 0, i8 3, i8 6 }
+'``unpredictable``' Metadata
+^^^^^^^^^^^^^^^^^^^^^
+
+``unpredictable`` metadata may be attached to any branch or switch
+instruction. It can be used to express the unpredictability of control
+flow. Similar to the llvm.expect intrinsic, it may be used to alter
+optimizations related to compare and branch instructions. The metadata
+is treated as a boolean value; if it exists, it signals that the branch
+or switch that it is attached to is completely unpredictable.
+
'``llvm.loop``'
^^^^^^^^^^^^^^^
::
- <resultval> = catchpad <resultty> [<args>*]
+ <resultval> = catchpad [<args>*]
to label <normal label> unwind label <exception label>
Overview:
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:
""""""""""
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:
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:
""""""""
.. 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:
'``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:
""""""""
::
- catchret label <normal>
+ catchret <value> to label <normal>
Overview:
"""""""""
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:
""""""""""
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:
::
- cleanupret <type> <value> unwind label <continue>
- cleanupret <type> <value> unwind to caller
+ cleanupret <value> unwind label <continue>
+ cleanupret <value> unwind to caller
Overview:
"""""""""
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:
""""""""""
: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:
::
- <resultval> = cleanuppad <resultty> [<args>*]
+ <resultval> = cleanuppad [<args>*]
Overview:
"""""""""
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:
""""""""""
""""""""""
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,
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:
Overview:
"""""""""
-The ``llvm.uabsdiff`` intrinsic returns a vector result of the absolute difference of the two operands,
-treating them both as unsigned integers.
+The ``llvm.uabsdiff`` intrinsic returns a vector result of the absolute difference of
+the two operands, treating them both as unsigned integers.
-The ``llvm.sabsdiff`` intrinsic returns a vector result of the absolute difference of the two operands,
-treating them both as signed integers.
+The ``llvm.sabsdiff`` intrinsic returns a vector result of the absolute difference of
+the two operands, treating them both as signed integers.
.. note::