[commit: ghc] master: primops: Add comment describing type of atomicModifyMutVar# (d91b104)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/d91b10458885aede47ff17fa649b2c0fd9fdf3ca/ghc

>---------------------------------------------------------------

commit d91b10458885aede47ff17fa649b2c0fd9fdf3ca
Author: Ben Gamari <bgamari.foss at gmail.com>
Date:   Mon Mar 6 17:31:20 2017 -0500

    primops: Add comment describing type of atomicModifyMutVar#
    
    This resolves #13130. It's not entirely clear to me why we don't use an
    unboxed tuple here but this is at least better than the status quo.
    
    [skip ci]
    
    Test Plan: Read it
    
    Reviewers: simonmar, austin, dfeuer
    
    Reviewed By: dfeuer
    
    Subscribers: dfeuer, rwbarton, thomie
    
    Differential Revision: https://phabricator.haskell.org/D3288


>---------------------------------------------------------------

d91b10458885aede47ff17fa649b2c0fd9fdf3ca
 compiler/prelude/primops.txt.pp | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/compiler/prelude/primops.txt.pp b/compiler/prelude/primops.txt.pp
index 855bdfc..11928b6 100644
--- a/compiler/prelude/primops.txt.pp
+++ b/compiler/prelude/primops.txt.pp
@@ -1924,13 +1924,25 @@ primop  WriteMutVarOp "writeMutVar#"  GenPrimOp
 primop  SameMutVarOp "sameMutVar#" GenPrimOp
    MutVar# s a -> MutVar# s a -> Int#
 
--- not really the right type, but we don't know about pairs here.  The
--- correct type is
+-- Note [Why not an unboxed tuple in atomicModifyMutVar#?]
+-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 --
---   MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
+-- Looking at the type of atomicModifyMutVar#, one might wonder why
+-- it doesn't return an unboxed tuple. e.g.,
 --
+--   MutVar# s a -> (a -> (# a, b #)) -> State# s -> (# State# s, b #)
+--
+-- The reason is that atomicModifyMutVar# relies on laziness for its atomicity.
+-- Given a MutVar# containing x, atomicModifyMutVar# merely replaces the
+-- its contents with a thunk of the form (fst (f x)). This can be done using an
+-- atomic compare-and-swap as it is merely replacing a pointer.
+
 primop  AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
    MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
+   { Modify the contents of a {\tt MutVar\#}. Note that this isn't strictly
+     speaking the correct type for this function, it should really be
+     {\tt MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)}, however
+     we don't know about pairs here. }
    with
    out_of_line = True
    has_side_effects = True