Improve and document atomicModifyMutVar2#

The primop atomicModifyMutVar2# is ill-documented, and its type is extremely odd. Its declared type (in primops.txt.pp is

   MutVar# s a -> (a -> c) -> State# s -> (# State# s, a, c #)

but that's a lie. Its real type is more like this

   MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, a, (a, b) #)

And there is other tricky and entirely un-documented stuff about it. It all comes from an accepted GHC Proposal 149: replace atomicModifyMutVar# primop, but much is unclear about it (to me anyway).

These topics are discussed in this email thread.

The thread ends up saying: I propose:

• To give atomicModifyMutVar2# its proper type, with a pair, as in the proposal.
• To do that, fiddle with genprimopcode, to allow it to parse tuples as well as unboxed tuples; not hard.
• This would disallow all this stuff about “any type that has a first field looking like a”, restricting to pairs alone. This didn’t form part of the proposal, and was never documented.
• Add a bit more clarity to the documentation, so it’d clear what must be forced.

This ticket is to record this task.

I've even done quite a bit of the work: see branch wip/T17693.