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