[Git][ghc/ghc][master] 4 commits: improve docs for casArray and casSmallArray
Marge Bot
gitlab at gitlab.haskell.org
Sun Apr 21 13:19:23 UTC 2019
Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC
Commits:
3e963de3 by Andrew Martin at 2019-04-21T13:13:20Z
improve docs for casArray and casSmallArray
- - - - -
98bffb07 by Andrew Martin at 2019-04-21T13:13:20Z
[skip ci] say "machine words" instead of "Int units" in the primops docs
- - - - -
3aefc14a by Andrew Martin at 2019-04-21T13:13:20Z
[skip ci] correct formatting of casArray# in docs for casSmallArray#
- - - - -
0e96d120 by Andrew Martin at 2019-04-21T13:13:20Z
[skip ci] correct the docs for casArray a little more. clarify that the returned element may be two different things
- - - - -
1 changed file:
- compiler/prelude/primops.txt.pp
Changes:
=====================================
compiler/prelude/primops.txt.pp
=====================================
@@ -1133,7 +1133,18 @@ primop ThawArrayOp "thawArray#" GenPrimOp
primop CasArrayOp "casArray#" GenPrimOp
MutableArray# s a -> Int# -> a -> a -> State# s -> (# State# s, Int#, a #)
- {Unsafe, machine-level atomic compare and swap on an element within an Array.}
+ {Given an array, an offset, the expected old value, and
+ the new value, perform an atomic compare and swap (i.e. write the new
+ value if the current value and the old value are the same pointer).
+ Returns 0 if the swap succeeds and 1 if it fails. Additionally, returns
+ the element at the offset after the operation completes. This means that
+ on a success the new value is returned, and on a failure the actual old
+ value (not the expected one) is returned. Implies a full memory barrier.
+ The use of a pointer equality on a lifted value makes this function harder
+ to use correctly than {\tt casIntArray\#}. All of the difficulties
+ of using {\tt reallyUnsafePtrEquality\#} correctly apply to
+ {\tt casArray\#} as well.
+ }
with
out_of_line = True
has_side_effects = True
@@ -1298,7 +1309,8 @@ primop ThawSmallArrayOp "thawSmallArray#" GenPrimOp
primop CasSmallArrayOp "casSmallArray#" GenPrimOp
SmallMutableArray# s a -> Int# -> a -> a -> State# s -> (# State# s, Int#, a #)
- {Unsafe, machine-level atomic compare and swap on an element within an array.}
+ {Unsafe, machine-level atomic compare and swap on an element within an array.
+ See the documentation of {\tt casArray\#}.}
with
out_of_line = True
has_side_effects = True
@@ -1562,13 +1574,13 @@ primop ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
primop ReadByteArrayOp_Int "readIntArray#" GenPrimOp
MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
- {Read integer; offset in words.}
+ {Read integer; offset in machine words.}
with has_side_effects = True
can_fail = True
primop ReadByteArrayOp_Word "readWordArray#" GenPrimOp
MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
- {Read word; offset in words.}
+ {Read word; offset in machine words.}
with has_side_effects = True
can_fail = True
@@ -1942,21 +1954,21 @@ primop SetByteArrayOp "setByteArray#" GenPrimOp
primop AtomicReadByteArrayOp_Int "atomicReadIntArray#" GenPrimOp
MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
- {Given an array and an offset in Int units, read an element. The
+ {Given an array and an offset in machine words, read an element. The
index is assumed to be in bounds. Implies a full memory barrier.}
with has_side_effects = True
can_fail = True
primop AtomicWriteByteArrayOp_Int "atomicWriteIntArray#" GenPrimOp
MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
- {Given an array and an offset in Int units, write an element. The
+ {Given an array and an offset in machine words, write an element. The
index is assumed to be in bounds. Implies a full memory barrier.}
with has_side_effects = True
can_fail = True
primop CasByteArrayOp_Int "casIntArray#" GenPrimOp
MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> (# State# s, Int# #)
- {Given an array, an offset in Int units, the expected old value, and
+ {Given an array, an offset in machine words, the expected old value, and
the new value, perform an atomic compare and swap i.e. write the new
value if the current value matches the provided old value. Returns
the value of the element before the operation. Implies a full memory
@@ -1966,7 +1978,7 @@ primop CasByteArrayOp_Int "casIntArray#" GenPrimOp
primop FetchAddByteArrayOp_Int "fetchAddIntArray#" GenPrimOp
MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
- {Given an array, and offset in Int units, and a value to add,
+ {Given an array, and offset in machine words, and a value to add,
atomically add the value to the element. Returns the value of the
element before the operation. Implies a full memory barrier.}
with has_side_effects = True
@@ -1974,7 +1986,7 @@ primop FetchAddByteArrayOp_Int "fetchAddIntArray#" GenPrimOp
primop FetchSubByteArrayOp_Int "fetchSubIntArray#" GenPrimOp
MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
- {Given an array, and offset in Int units, and a value to subtract,
+ {Given an array, and offset in machine words, and a value to subtract,
atomically substract the value to the element. Returns the value of
the element before the operation. Implies a full memory barrier.}
with has_side_effects = True
@@ -1982,7 +1994,7 @@ primop FetchSubByteArrayOp_Int "fetchSubIntArray#" GenPrimOp
primop FetchAndByteArrayOp_Int "fetchAndIntArray#" GenPrimOp
MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
- {Given an array, and offset in Int units, and a value to AND,
+ {Given an array, and offset in machine words, and a value to AND,
atomically AND the value to the element. Returns the value of the
element before the operation. Implies a full memory barrier.}
with has_side_effects = True
@@ -1990,7 +2002,7 @@ primop FetchAndByteArrayOp_Int "fetchAndIntArray#" GenPrimOp
primop FetchNandByteArrayOp_Int "fetchNandIntArray#" GenPrimOp
MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
- {Given an array, and offset in Int units, and a value to NAND,
+ {Given an array, and offset in machine words, and a value to NAND,
atomically NAND the value to the element. Returns the value of the
element before the operation. Implies a full memory barrier.}
with has_side_effects = True
@@ -1998,7 +2010,7 @@ primop FetchNandByteArrayOp_Int "fetchNandIntArray#" GenPrimOp
primop FetchOrByteArrayOp_Int "fetchOrIntArray#" GenPrimOp
MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
- {Given an array, and offset in Int units, and a value to OR,
+ {Given an array, and offset in machine words, and a value to OR,
atomically OR the value to the element. Returns the value of the
element before the operation. Implies a full memory barrier.}
with has_side_effects = True
@@ -2006,7 +2018,7 @@ primop FetchOrByteArrayOp_Int "fetchOrIntArray#" GenPrimOp
primop FetchXorByteArrayOp_Int "fetchXorIntArray#" GenPrimOp
MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
- {Given an array, and offset in Int units, and a value to XOR,
+ {Given an array, and offset in machine words, and a value to XOR,
atomically XOR the value to the element. Returns the value of the
element before the operation. Implies a full memory barrier.}
with has_side_effects = True
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/compare/6ac5da7844023a896d4e4477ee6429fa0f35c6e4...0e96d1205905707369b82ce024afdfed3fd7bdf8
--
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/compare/6ac5da7844023a896d4e4477ee6429fa0f35c6e4...0e96d1205905707369b82ce024afdfed3fd7bdf8
You're receiving this email because of your account on gitlab.haskell.org.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20190421/6544db6b/attachment-0001.html>
More information about the ghc-commits
mailing list