-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Atomic compare and swap for IORefs and CASRefs.
--   
--   After GHC 7.2 a new `casMutVar#` primop became available, but was not
--   yet exposed in Data.IORef. This package fills that gap until such a
--   time as Data.IORef obsoletes it.
--   
--   Further, in addition to exposing native Haskell CAS operations, this
--   package contains "mockups" that imititate the same functionality using
--   either atomicModifyIORef and unsafe pointer equality (in
--   <tt>Data.CAS.Fake</tt>) or using foreign functions
--   (<tt>Data.CAS.Foreign</tt>). These alternatives are useful for
--   debugging.
--   
--   Note that the foreign option does not operate on IORefs and so is
--   directly interchangeable with <a>Data.CAS</a> and <a>Data.CAS.Fake</a>
--   only if the interface in <a>Data.CAS.Class</a> is used.
@package IORefCAS
@version 0.0.1.1


-- | A type class capturing mutable storage cells that support CAS
--   operations in the IO monad.
module Data.CAS.Internal.Class

-- | It would be nice to use an associated type family with this class (for
--   casref), but that would preclude overlapping instances.
class CASable casref a
newCASable :: CASable casref a => a -> IO (casref a)
readCASable :: CASable casref a => casref a -> IO a
writeCASable :: CASable casref a => casref a -> a -> IO ()
cas :: CASable casref a => casref a -> a -> a -> IO (Bool, a)
unsafeName :: a -> Int
ptrEq :: a -> a -> Bool


-- | This is an attempt to imitate a CAS using normal Haskell/GHC
--   operations. Useful for debugging.
module Data.CAS.Internal.Fake

-- | The type of references supporting CAS.
data CASRef a
casIORef :: IORef a -> a -> a -> IO (Bool, a)
ptrEq :: a -> a -> Bool
atomicModifyIORefCAS :: IORef a -> (a -> (a, b)) -> IO b
atomicModifyIORefCAS_ :: IORef a -> (a -> a) -> IO ()
instance CASable CASRef a


-- | This is a version of CAS that works outside of Haskell by using the
--   FFI (and the GCC intrinsics-based <tt>Data.Bits.Atomic</tt>.)
module Data.CAS.Internal.Foreign
data CASRef a
instance [overlap ok] CASable CASRef Word32


-- | Atomic compare and swap for IORefs and STRefs.
module Data.CAS

-- | Performs a machine-level compare and swap operation on an
--   <a>STRef</a>. Returns a tuple containing a <a>Bool</a> which is
--   <a>True</a> when a swap is performed, along with the <tt>current</tt>
--   value from the <a>STRef</a>.
casSTRef :: STRef s a -> a -> a -> ST s (Bool, a)

-- | Performs a machine-level compare and swap operation on an
--   <a>IORef</a>. Returns a tuple containing a <a>Bool</a> which is
--   <a>True</a> when a swap is performed, along with the <tt>current</tt>
--   value from the <a>IORef</a>.
casIORef :: IORef a -> a -> a -> IO (Bool, a)

-- | A drop-in replacement for <a>atomicModifyIORefCAS</a> that
--   optimistically attempts to compute the new value and CAS it into place
--   without introducing new thunks or locking anything. Note that this is
--   STRICTer than its standard counterpart and will only place evaluated
--   (WHNF) values in the IORef.
atomicModifyIORefCAS :: IORef a -> (a -> (a, b)) -> IO b

-- | A simpler version that modifies the state but does not return
--   anything.
atomicModifyIORefCAS_ :: IORef t -> (t -> t) -> IO ()
data CASRef a
instance CASable CASRef a