What does 'MutVar#' mean?

Question

I've been trying to read and understand the code that implements Haskell's ST monad, and I found this code:

{-# LANGUAGE Unsafe #-}
{-# LANGUAGE NoImplicitPrelude, MagicHash, UnboxedTuples #-}
{-# OPTIONS_HADDOCK hide #-}

-----------------------------------------------------------------------------
-- |
-- Module      :  GHC.STRef
-- Copyright   :  (c) The University of Glasgow, 1994-2002
-- License     :  see libraries/base/LICENSE
--
-- Maintainer  :  [email protected]
-- Stability   :  internal
-- Portability :  non-portable (GHC Extensions)
--
-- References in the 'ST' monad.
--
-----------------------------------------------------------------------------

module GHC.STRef (
        STRef(..),
        newSTRef, readSTRef, writeSTRef
    ) where

import GHC.ST
import GHC.Base

data STRef s a = STRef (MutVar# s a)
-- ^ a value of type @STRef s a@ is a mutable variable in state thread @s@,
-- containing a value of type @a@

-- |Build a new 'STRef' in the current state thread
newSTRef :: a -> ST s (STRef s a)
newSTRef init = ST $ \s1# ->
    case newMutVar# init s1#            of { (# s2#, var# #) ->
    (# s2#, STRef var# #) }

-- |Read the value of an 'STRef'
readSTRef :: STRef s a -> ST s a
readSTRef (STRef var#) = ST $ \s1# -> readMutVar# var# s1#

-- |Write a new value into an 'STRef'
writeSTRef :: STRef s a -> a -> ST s ()
writeSTRef (STRef var#) val = ST $ \s1# ->
    case writeMutVar# var# val s1#      of { s2# ->
    (# s2#, () #) }

-- Just pointer equality on mutable references:
instance Eq (STRef s a) where
    STRef v1# == STRef v2# = isTrue# (sameMutVar# v1# v2#)

I see the following line of code in the above code file :

data STRef s a = STRef (MutVar# s a)

A quick search on MutVar# yielded the following results :

• https://hackage.haskell.org/package/primitive-0.4.1/docs/src/Data-Primitive-MutVar.html#MutVar
• https://github.com/ghc/ghc/blob/228ddb95ee137e7cef02dcfe2521233892dd61e0/utils/genprimopcode/Main.hs#L816

My question is : What is MutVar#? Why isn't it defined anywhere ? What does it mean ?

Answer 1

MutVar# is a primitive type provided by the compiler itself. It represents a mutable reference, and forms the core of IORef and STRef.

In general, anything that ends in # is an implementation detail of GHC. Unless you're doing low-level hackery you don't need to worry about them. Most of these operations have wrappers (like ST) which are easier to use.

You can read more about these in the GHC manual and the ghc-prim package.