gcc: x86 transactional memory intrinsics

1 
1 6.59.34 x86 Transactional Memory Intrinsics
1 -------------------------------------------
1 
1 These hardware transactional memory intrinsics for x86 allow you to use
1 memory transactions with RTM (Restricted Transactional Memory).  This
1 support is enabled with the '-mrtm' option.  For using HLE (Hardware
11 Lock Elision) see ⇒x86 specific memory model extensions for
 transactional memory instead.
1 
1  A memory transaction commits all changes to memory in an atomic way, as
1 visible to other threads.  If the transaction fails it is rolled back
1 and all side effects discarded.
1 
1  Generally there is no guarantee that a memory transaction ever succeeds
1 and suitable fallback code always needs to be supplied.
1 
1  -- RTM Function: unsigned _xbegin ()
1      Start a RTM (Restricted Transactional Memory) transaction.  Returns
1      '_XBEGIN_STARTED' when the transaction started successfully (note
1      this is not 0, so the constant has to be explicitly tested).
1 
1      If the transaction aborts, all side effects are undone and an abort
1      code encoded as a bit mask is returned.  The following macros are
1      defined:
1 
1      '_XABORT_EXPLICIT'
1           Transaction was explicitly aborted with '_xabort'.  The
1           parameter passed to '_xabort' is available with
1           '_XABORT_CODE(status)'.
1      '_XABORT_RETRY'
1           Transaction retry is possible.
1      '_XABORT_CONFLICT'
1           Transaction abort due to a memory conflict with another
1           thread.
1      '_XABORT_CAPACITY'
1           Transaction abort due to the transaction using too much
1           memory.
1      '_XABORT_DEBUG'
1           Transaction abort due to a debug trap.
1      '_XABORT_NESTED'
1           Transaction abort in an inner nested transaction.
1 
1      There is no guarantee any transaction ever succeeds, so there
1      always needs to be a valid fallback path.
1 
1  -- RTM Function: void _xend ()
1      Commit the current transaction.  When no transaction is active this
1      faults.  All memory side effects of the transaction become visible
1      to other threads in an atomic manner.
1 
1  -- RTM Function: int _xtest ()
1      Return a nonzero value if a transaction is currently active,
1      otherwise 0.
1 
1  -- RTM Function: void _xabort (status)
1      Abort the current transaction.  When no transaction is active this
1      is a no-op.  The STATUS is an 8-bit constant; its value is encoded
1      in the return value from '_xbegin'.
1 
1  Here is an example showing handling for '_XABORT_RETRY' and a fallback
1 path for other failures:
1 
1      #include <immintrin.h>
1 
1      int n_tries, max_tries;
1      unsigned status = _XABORT_EXPLICIT;
1      ...
1 
1      for (n_tries = 0; n_tries < max_tries; n_tries++)
1        {
1          status = _xbegin ();
1          if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY))
1            break;
1        }
1      if (status == _XBEGIN_STARTED)
1        {
1          ... transaction code...
1          _xend ();
1        }
1      else
1        {
1          ... non-transactional fallback path...
1        }
1 
1 Note that, in most cases, the transactional and non-transactional code
1 must synchronize together to ensure consistency.
1