gcc/doc/gcc/extensions-to-the-c-language-family/target-builtins/x86-transactional-memory-intrinsics.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _x86-transactional-memory-intrinsics:
   7
   8 x86 Transactional Memory Intrinsics
   9 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 These hardware transactional memory intrinsics for x86 allow you to use
  12 memory transactions with RTM (Restricted Transactional Memory).
  13 This support is enabled with the :option:`-mrtm` option.
  14 For using HLE (Hardware Lock Elision) see
  15 :ref:`x86-specific-memory-model-extensions-for-transactional-memory` instead.
  16
  17 A memory transaction commits all changes to memory in an atomic way,
  18 as visible to other threads. If the transaction fails it is rolled back
  19 and all side effects discarded.
  20
  21 Generally there is no guarantee that a memory transaction ever succeeds
  22 and suitable fallback code always needs to be supplied.
  23
  24 .. function:: unsigned _xbegin ()
  25
  26   Start a RTM (Restricted Transactional Memory) transaction.
  27   Returns ``_XBEGIN_STARTED`` when the transaction
  28   started successfully (note this is not 0, so the constant has to be
  29   explicitly tested).
  30
  31   If the transaction aborts, all side effects
  32   are undone and an abort code encoded as a bit mask is returned.
  33   The following macros are defined:
  34
  35   ``_XABORT_EXPLICIT``
  36     Transaction was explicitly aborted with ``_xabort``.  The parameter passed
  37     to ``_xabort`` is available with ``_XABORT_CODE(status)``.
  38
  39   ``_XABORT_RETRY``
  40     Transaction retry is possible.
  41
  42   ``_XABORT_CONFLICT``
  43     Transaction abort due to a memory conflict with another thread.
  44
  45   ``_XABORT_CAPACITY``
  46     Transaction abort due to the transaction using too much memory.
  47
  48   ``_XABORT_DEBUG``
  49     Transaction abort due to a debug trap.
  50
  51   ``_XABORT_NESTED``
  52     Transaction abort in an inner nested transaction.
  53
  54   There is no guarantee
  55   any transaction ever succeeds, so there always needs to be a valid
  56   fallback path.
  57
  58 .. function:: void _xend ()
  59
  60   Commit the current transaction. When no transaction is active this faults.
  61   All memory side effects of the transaction become visible
  62   to other threads in an atomic manner.
  63
  64 .. function:: int _xtest ()
  65
  66   Return a nonzero value if a transaction is currently active, otherwise 0.
  67
  68 .. function:: void _xabort (status)
  69
  70   Abort the current transaction. When no transaction is active this is a no-op.
  71   The :samp:`{status}` is an 8-bit constant; its value is encoded in the return
  72   value from ``_xbegin``.
  73
  74 Here is an example showing handling for ``_XABORT_RETRY``
  75 and a fallback path for other failures:
  76
  77 .. code-block:: c++
  78
  79   #include <immintrin.h>
  80
  81   int n_tries, max_tries;
  82   unsigned status = _XABORT_EXPLICIT;
  83   ...
  84
  85   for (n_tries = 0; n_tries < max_tries; n_tries++)
  86     {
  87       status = _xbegin ();
  88       if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY))
  89         break;
  90     }
  91   if (status == _XBEGIN_STARTED)
  92     {
  93       ... transaction code...
  94       _xend ();
  95     }
  96   else
  97     {
  98       ... non-transactional fallback path...
  99     }
 100
 101 Note that, in most cases, the transactional and non-transactional code
 102 must synchronize together to ensure consistency.