[Git][ghc/ghc][master] Improve documentation of atomicModifyMutVar2#

[Marge Bot (@marge-bot)]

Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC


Commits:
62fa7faa by Bodigrim at 2023-03-25T00:05:22-04:00
Improve documentation of atomicModifyMutVar2#

- - - - -


1 changed file:

- compiler/GHC/Builtin/primops.txt.pp


Changes:

=====================================
compiler/GHC/Builtin/primops.txt.pp
=====================================
@@ -2528,11 +2528,23 @@ primop  WriteMutVarOp "writeMutVar#"  GenPrimOp
 primop  AtomicModifyMutVar2Op "atomicModifyMutVar2#" GenPrimOp
    MutVar# s a -> (a -> c) -> State# s -> (# State# s, a, c #)
    { Modify the contents of a 'MutVar#', returning the previous
-     contents and the result of applying the given function to the
-     previous contents. Note that this isn't strictly
-     speaking the correct type for this function; it should really be
-     @'MutVar#' s a -> (a -> (a,b)) -> 'State#' s -> (# 'State#' s, a, (a, b) #)@,
-     but we don't know about pairs here. }
+     contents @x :: a@ and the result of applying the given function to the
+     previous contents @f x :: c at .
+
+     The @data@ type @c@ (not a @newtype@!) must be a record whose first field
+     is of lifted type @a :: Type@ and is not unpacked. For example, product
+     types @c ~ Solo a@ or @c ~ (a, b)@ work well. If the record type is both
+     monomorphic and strict in its first field, it's recommended to mark the
+     latter @{-# NOUNPACK #-}@ explicitly.
+
+     Under the hood 'atomicModifyMutVar2#' atomically replaces a pointer to an
+     old @x :: a@ with a pointer to a selector thunk @fst r@, where
+     @fst@ is a selector for the first field of the record and @r@ is a
+     function application thunk @r = f x at .
+
+     @atomicModifyIORef2Native@ from @atomic-modify-general@ package makes an
+     effort to reflect restrictions on @c@ faithfully, providing a
+     well-typed high-level wrapper.}
    with
    out_of_line = True
    has_side_effects = True



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/62fa7faaf8ca2d34cda3e3b7c4c6b2d13efa16fe

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/62fa7faaf8ca2d34cda3e3b7c4c6b2d13efa16fe
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/20230325/a489d4a4/attachment-0001.html>