.\"
.\" Copyright 2013 Samy Al Bahra.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"
.Dd December 17, 2013
.Dt ck_pr_rtm 3
.Sh NAME
.Nm ck_pr_rtm_begin ,
.Nm ck_pr_rtm_end ,
.Nm ck_pr_rtm_abort ,
.Nm ck_pr_rtm_test
.Nd restricted transactional memory
.Sh LIBRARY
Concurrency Kit (libck, \-lck)
.Sh SYNOPSIS
.In ck_pr.h
.Ft unsigned int
.Fn ck_pr_rtm_begin "void"
.Ft void
.Fn ck_pr_rtm_end "void"
.Ft void
.Fn ck_pr_rtm_abort "const unsigned int status"
.Ft bool
.Fn ck_pr_rtm_test "void"
.Sh DESCRIPTION
These family of functions implement support for restricted
transactional memory, if available on the underlying platform.
Currently, support is only provided for Intel Haswell and
newer x86 microarchitectures that have the TSX-NI feature.
.Pp
The
.Fn ck_pr_rtm_begin
function returns CK_PR_RTM_STARTED if a transaction was successfully
started. In case of an abort, either internal (through a ck_pr_rtm_abort)
or external, program flow will return to the point which the function
was called except the return value will consist of a bitmap with one or
more of the following bits set:
.Bl -tag -width indent
.It CK_PR_RTM_EXPLICIT
Set if the transactionally was explicitly aborted through
.Fn ck_pr_rtm_abort .
.It CK_PR_RTM_RETRY
Set if the transaction failed but can still succeed if
retried.
.It CK_PR_RTM_CONFLICT
The transaction failed due to a conflict in one of the memory
addresses that are part of the working set of the transaction.
.It CK_PR_RTM_CAPACITY
Set if the architecture-defined transaction size limit was exceeded.
.It CK_PR_RTM_DEBUG
Set if a hardware breakpoint was triggered.
.It CK_PR_RTM_NESTED
Set if a nested transaction failed.
.El
.Pp
The user is also able to specify a one byte abort status
by calling
.Fn ck_pr_rtm_abort .
This status byte can be extracted by calling the
.Fn CK_PR_RTM_CODE
function with the return value of
.Fn ck_pr_rtm_begin
as an argument. The return value of
.Fn CK_PR_RTM_CODE
will be the value of this status byte.
For additional information, please see the Intel instruction
set manuals.
.Sh SEE ALSO
.Xr ck_pr_fence_load 3 ,
.Xr ck_pr_fence_load_depends 3 ,
.Xr ck_pr_fence_store 3 ,
.Xr ck_pr_fence_memory 3 ,
.Xr ck_pr_load 3 ,
.Xr ck_pr_store 3 ,
.Xr ck_pr_fas 3 ,
.Xr ck_pr_faa 3 ,
.Xr ck_pr_inc 3 ,
.Xr ck_pr_dec 3 ,
.Xr ck_pr_neg 3 ,
.Xr ck_pr_not 3 ,
.Xr ck_pr_sub 3 ,
.Xr ck_pr_and 3 ,
.Xr ck_pr_or 3 ,
.Xr ck_pr_xor 3 ,
.Xr ck_pr_add 3 ,
.Xr ck_pr_btc 3 ,
.Xr ck_pr_bts 3 ,
.Xr ck_pr_btr 3
.Pp
Additional information available at http://concurrencykit.org/