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


-- | An atomic counter implemented using the FFI.
--   
--   An atomic counter implemented using the FFI.
@package atomic-primops-foreign
@version 0.6


-- | This implementation stores an unboxed counter and uses FFI operations
--   to modify its contents. It has the advantage that it can use true
--   fetch-and-add operations. It has the disadvantage of extra overhead
--   due to FFI calls.
--   
--   For more documentation, see the module <a>Data.Atomics.Counter</a>,
--   which exports the same interface as this module.
module Data.Atomics.Counter.Foreign

-- | The type of mutable atomic counters.
type AtomicCounter = ForeignPtr Int

-- | You should not depend on this type. It varies between different
--   implementations of atomic counters.
type CTicket = Int

-- | Create a new counter initialized to the given value.
newCounter :: Int -> IO AtomicCounter

-- | Just like the <a>Data.Atomics</a> CAS interface, this routine returns
--   an opaque ticket that can be used in CAS operations.
readCounterForCAS :: AtomicCounter -> IO CTicket

-- | Equivalent to <a>readCounterForCAS</a> followed by <a>peekCTicket</a>.
readCounter :: AtomicCounter -> IO Int

-- | Opaque tickets cannot be constructed, but they can be destructed into
--   values.
peekCTicket :: CTicket -> Int

-- | Make a non-atomic write to the counter. No memory-barrier.
writeCounter :: AtomicCounter -> Int -> IO ()

-- | Compare and swap for the counter ADT.
casCounter :: AtomicCounter -> CTicket -> Int -> IO (Bool, CTicket)

-- | Increment the counter by a given amount. Returns the original value
--   before the increment.
--   
--   Note that UNLIKE with boxed implementations of counters, where
--   increment is based on CAS, this increment is <i>O(1)</i>.
--   Fetch-and-add does not require a retry loop like CAS.
incrCounter :: Int -> AtomicCounter -> IO Int

-- | An alternate version for when you don't care about the old value.
incrCounter_ :: Int -> AtomicCounter -> IO ()