-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Mutable variable with primitive values -- -- Mutable variable PVar that is backed by a single value -- MutableByteArray @package pvar @version 0.2.0.0 module Data.Primitive.PVar.Unsafe -- | Mutable variable with primitive value. data PVar m a PVar :: MutableByteArray# (PrimState m) -> PVar m a -- | Create a mutable variable in unpinned and unititialized memory rawPVar :: forall a m. (PrimMonad m, Prim a) => m (PVar m a) -- | Create a mutable variable in pinned memory with uninitialized memory. rawPinnedPVar :: forall a m. (PrimMonad m, Prim a) => m (PVar m a) -- | Create a mutable variable in pinned uninitialized memory. rawAlignedPinnedPVar :: forall a m. (PrimMonad m, Prim a) => m (PVar m a) -- | Create a mutable variable in pinned uninitialized memory using -- Storable interface for getting the number of bytes for memory -- allocation. rawStorablePVar :: forall a m. (PrimMonad m, Storable a) => m (PVar m a) -- | Create a mutable variable in pinned uninitialized memory using -- Storable interface for getting the number of bytes for memory -- allocation and alignement. rawAlignedStorablePVar :: forall a m. (PrimMonad m, Storable a) => m (PVar m a) -- | Use Storable reading functionality inside the PrimMonad. peekPrim :: (Storable a, PrimMonad m) => Ptr a -> m a -- | Use Storable wrting functionality inside the PrimMonad. pokePrim :: (Storable a, PrimMonad m) => Ptr a -> a -> m () -- | Extract the address to the mutable variable, but only if it is backed -- by pinned memory. It is unsafe because even for pinned memory memory -- can be deallocated if associated PVar goes out of scope. Use -- withPtrPVar or toForeignPtr instead. toPtrPVar :: PVar m a -> Maybe (Ptr a) -- | Get the address to the contents. This is highly unsafe, espcially if -- memory is not pinned unsafeToPtrPVar :: PVar m a -> Ptr a -- | Convert PVar into a ForeignPtr, very unsafe if not -- backed by pinned memory. unsafeToForeignPtrPVar :: PVar IO a -> ForeignPtr a -- | Reset contents of a mutable variable to zero. zeroPVar :: (PrimMonad m, Prim a) => PVar m a -> m () -- | Get the size of the mutable variable in bytes as an unpacked integer sizeOfPVar# :: forall m a. Prim a => PVar m a -> Int# -- | Get the alignment of the mutable variable in bytes as an unpacked -- integer alignmentPVar# :: forall m a. Prim a => PVar m a -> Int# -- | Fill the contents of mutable variable with byte c setPVar# :: (PrimMonad m, Prim a) => PVar m a -> Int# -> m () -- | Using casIntArray# perform atomic modification of an integer -- element in a MutableByteArray#. Implies a full memory barrier. atomicModifyIntArray# :: MutableByteArray# d -> Int# -> (Int# -> (# Int#, b #)) -> State# d -> (# State# d, b #) -- | Uses casIntArray# to perform atomic modification of an integer -- element in a MutableByteArray#. Implies a full memory barrier. atomicModifyIntArray_# :: MutableByteArray# d -> Int# -> (Int# -> Int#) -> State# d -> State# d -- | Copy the value from a frozen ByteArray into a mutable variable -- at specified index. Index of array is not checked and can result in an -- unchecked exception when incorrect copyFromByteArrayPVar :: (PrimMonad m, Prim a) => ByteArray -> Int -> PVar m a -> m () -- | Copy the value from MutableByteArray at specified index into the -- mutable variable. Index of array is not checked and can result in an -- unchecked exception when incorrect copyFromMutableByteArrayPVar :: (PrimMonad m, Prim a) => MutableByteArray (PrimState m) -> Int -> PVar m a -> m () -- | Copy the value from a mutable variable into a mutable array at the -- specified index. Index of array is not checked and can result in an -- unchecked exception when incorrect copyPVarToMutableByteArray :: (PrimMonad m, Prim a) => PVar m a -> MutableByteArray (PrimState m) -> Int -> m () -- | Check whether or not the ByteArray is pinned. -- -- Note - This function uses GHC built-in functions for GHC -- 8.2 and newer, but for older versions it fallsback onto custom -- implementation. isByteArrayPinned :: ByteArray -> Bool -- | Check whether or not the MutableByteArray is pinned. -- -- Note - This function uses GHC built-in functions for GHC -- 8.2 and newer, but for older versions it fallsback onto custom -- implementation. isMutableByteArrayPinned :: MutableByteArray s -> Bool -- | Determine whether a ByteArray# is guaranteed not to move -- during GC. isByteArrayPinned# :: ByteArray# -> Int# -- | Determine whether a MutableByteArray# is guaranteed not to -- move during GC. isMutableByteArrayPinned# :: () => MutableByteArray# d -> Int# -- | Show the type name showsType :: Typeable t => proxy t -> ShowS -- | Unwrap the primitive Int unI# :: Int -> Int# module Data.Primitive.PVar -- | Mutable variable with primitive value. data PVar m a -- | Create a mutable variable in unpinned memory (i.e. GC can move it) -- with an initial value. This is a prefered way to create a mutable -- variable, since it will not contribute to memory fragmentation. For -- pinned memory versions see newPinnedPVar and -- newAlignedPinnedPVar newPVar :: (PrimMonad m, Prim a) => a -> m (PVar m a) -- | Run an ST action on a mutable variable. withPVarST :: Prim p => p -> (forall s. PVar (ST s) p -> ST s a) -> a -- | Read a value from a mutable variable readPVar :: (PrimMonad m, Prim a) => PVar m a -> m a -- | Write a value into a mutable variable writePVar :: (PrimMonad m, Prim a) => PVar m a -> a -> m () -- | Apply a pure function to the contents of a mutable variable. Returns -- the artifact of computation. modifyPVar :: (PrimMonad m, Prim a) => PVar m a -> (a -> (a, b)) -> m b -- | Apply a pure function to the contents of a mutable variable. modifyPVar_ :: (PrimMonad m, Prim a) => PVar m a -> (a -> a) -> m () -- | Apply a pure function to the contents of a mutable variable. Returns -- the old value. fetchModifyPVar :: (PrimMonad m, Prim a) => PVar m a -> (a -> a) -> m a -- | Apply a pure function to the contents of a mutable variable. Returns -- the new value. modifyFetchPVar :: (PrimMonad m, Prim a) => PVar m a -> (a -> a) -> m a -- | Apply a monadic action to the contents of a mutable variable. Returns -- the artifact of computation. modifyPVarM :: (PrimMonad m, Prim a) => PVar m a -> (a -> m (a, b)) -> m b -- | Apply a monadic action to the contents of a mutable variable. modifyPVarM_ :: (PrimMonad m, Prim a) => PVar m a -> (a -> m a) -> m () -- | Apply a monadic action to the contents of a mutable variable. Returns -- the old value. fetchModifyPVarM :: (PrimMonad m, Prim a) => PVar m a -> (a -> m a) -> m a -- | Apply a monadic action to the contents of a mutable variable. Returns -- the new value. modifyFetchPVarM :: (PrimMonad m, Prim a) => PVar m a -> (a -> m a) -> m a -- | Swap contents of two mutable variables. swapPVars_ :: (PrimMonad m, Prim a) => PVar m a -> PVar m a -> m () -- | Swap contents of two mutable variables. Returns their old values. swapPVars :: (PrimMonad m, Prim a) => PVar m a -> PVar m a -> m (a, a) -- | Copy contents of one mutable variable PVar into another copyPVar :: (PrimMonad m, Prim a) => PVar m a -> PVar m a -> m () -- | Size in bytes of a value stored inside the mutable variable. -- PVar itself is neither accessed nor evaluated. sizeOfPVar :: Prim a => PVar m a -> Int -- | Alignment in bytes of the value stored inside of the mutable variable. -- PVar itself is neither accessed nor evaluated. alignmentPVar :: Prim a => PVar m a -> Int -- | Create a mutable variable in pinned memory with an initial value. newPinnedPVar :: (PrimMonad m, Prim a) => a -> m (PVar m a) -- | Create a mutable variable in pinned memory with an initial value and -- aligned according to its alignment newAlignedPinnedPVar :: (PrimMonad m, Prim a) => a -> m (PVar m a) -- | Apply an action to the Ptr that references the mutable -- variable, but only if it is backed by pinned memory, cause otherwise -- it would be unsafe. withPtrPVar :: (PrimMonad m, Prim a) => PVar n a -> (Ptr a -> m b) -> m (Maybe b) -- | Apply an action to the newly allocated PVar and to the -- Ptr that references it. Memory allocated with number of bytes -- specified by sizeOf a is allocated and pinned, -- therefore it is safe to operate directly with the pointer as well as -- over FFI. Returning the pointer from the supplied action would be very -- unsafe, therefore return the PVar if you still need it -- afterwards, garbage collector will cleanup the memory when it is no -- longer needed. withStorablePVar :: (PrimMonad m, Storable a) => a -> (PVar m a -> Ptr a -> m b) -> m b -- | Same withStorablePVar, except memory is aligned according to -- alignment. withAlignedStorablePVar :: (PrimMonad m, Storable a) => a -> (PVar m a -> Ptr a -> m b) -> m b -- | Copy contents of a mutable variable PVar into a pointer -- Ptr copyPVarToPtr :: (PrimMonad m, Prim a) => PVar m a -> Ptr a -> m () -- | Convert PVar into a ForeignPtr, but only if it is backed -- by pinned memory. toForeignPtrPVar :: PVar IO a -> Maybe (ForeignPtr a) -- | Check if PVar is backed by pinned memory or not isPinnedPVar :: PVar m a -> Bool -- | Use Storable reading functionality inside the PrimMonad. peekPrim :: (Storable a, PrimMonad m) => Ptr a -> m a -- | Use Storable wrting functionality inside the PrimMonad. pokePrim :: (Storable a, PrimMonad m) => Ptr a -> a -> m () -- | Apply a function to an integer element of a PVar atomically. -- Implies a full memory barrier. atomicModifyIntPVar :: PrimMonad m => PVar m Int -> (Int -> (Int, a)) -> m a -- | Apply a function to an integer element of a PVar atomically. -- Returns the old value. Implies a full memory barrier. atomicModifyIntPVar_ :: PrimMonad m => PVar m Int -> (Int -> Int) -> m () -- | Apply a function to an integer element of a PVar atomically. -- Implies a full memory barrier. Returns the new value. atomicFetchModifyIntPVar :: PrimMonad m => PVar m Int -> (Int -> Int) -> m Int -- | Apply a function to an integer element of a PVar atomically. -- Implies a full memory barrier. Returns the new value. atomicModifyFetchIntPVar :: PrimMonad m => PVar m Int -> (Int -> Int) -> m Int -- | Create a new PVar in pinned memory with an initial value in it -- aligned on the size of an Int. Implies a full memory barrier. atomicReadIntPVar :: PrimMonad m => PVar m Int -> m Int -- | Write a value into an PVar atomically. Implies a full memory -- barrier. atomicWriteIntPVar :: PrimMonad m => PVar m Int -> Int -> m () -- | Compare and swap. This is also a function that is used to implement -- atomicModifyIntPVar. Implies a full memory barrier. casIntPVar :: PrimMonad m => PVar m Int -> Int -> Int -> m Int -- | Add two numbers, corresponds to (+) done atomically. -- Returns the previous value of the mutable variable. Implies a full -- memory barrier. atomicAddIntPVar :: PrimMonad m => PVar m Int -> Int -> m Int -- | Subtract two numbers, corresponds to (-) done -- atomically. Returns the previous value of the mutable variable. -- Implies a full memory barrier. atomicSubIntPVar :: PrimMonad m => PVar m Int -> Int -> m Int -- | Binary conjuction (AND), corresponds to (.&.) done -- atomically. Returns the previous value of the mutable variable. -- Implies a full memory barrier. atomicAndIntPVar :: PrimMonad m => PVar m Int -> Int -> m Int -- | Binary negation of conjuction (NAND), corresponds to \x y -> -- complement (x .&. y) done atomically. Returns -- the previous value of the mutable variable. Implies a full memory -- barrier. atomicNandIntPVar :: PrimMonad m => PVar m Int -> Int -> m Int -- | Binary disjunction (OR), corresponds to (.|.) done -- atomically. Returns the previous value of the mutable variable. -- Implies a full memory barrier. atomicOrIntPVar :: PrimMonad m => PVar m Int -> Int -> m Int -- | Binary exclusive disjunction (XOR), corresponds to xor -- done atomically. Returns the previous value of the mutable variable. -- Implies a full memory barrier. atomicXorIntPVar :: PrimMonad m => PVar m Int -> Int -> m Int -- | Binary negation (NOT), corresponds to ones' complement -- done atomically. Returns the previous value of the mutable variable. -- Implies a full memory barrier. atomicNotIntPVar :: PrimMonad m => PVar m Int -> m Int -- | Class of types supporting primitive array operations. This includes -- interfacing with GC-managed memory (functions suffixed with -- ByteArray#) and interfacing with unmanaged memory (functions -- suffixed with Addr#). Endianness is platform-dependent. class Prim a -- | Class of monads which can perform primitive state-transformer actions class Monad m => PrimMonad (m :: Type -> Type) where { -- | State token type type family PrimState (m :: Type -> Type) :: Type; } -- | RealWorld is deeply magical. It is primitive, but it -- is not unlifted (hence ptrArg). We never manipulate -- values of type RealWorld; it's only used in the type system, -- to parameterise State#. data RealWorld :: Type -- | Size of values of type a. The argument is not used. -- -- This function has existed since 0.1, but was moved from -- Primitive to Types in version 0.6.3.0 sizeOf :: Prim a => a -> Int -- | Alignment of values of type a. The argument is not used. -- -- This function has existed since 0.1, but was moved from -- Primitive to Types in version 0.6.3.0 alignment :: Prim a => a -> Int -- | The strict state-transformer monad. A computation of type -- ST s a transforms an internal state indexed by -- s, and returns a value of type a. The s -- parameter is either -- -- -- -- It serves to keep the internal states of different invocations of -- runST separate from each other and from invocations of -- stToIO. -- -- The >>= and >> operations are strict in the -- state (though not in values stored in the state). For example, -- -- 
--   runST (writeSTRef _|_ v >>= f) = _|_
--
data ST s a -- | Return the value computed by a state transformer computation. The -- forall ensures that the internal state used by the ST -- computation is inaccessible to the rest of the program. runST :: () => (forall s. () => ST s a) -> a -- | The member functions of this class facilitate writing values of -- primitive types to raw memory (which may have been allocated with the -- above mentioned routines) and reading values from blocks of raw -- memory. The class, furthermore, includes support for computing the -- storage requirements and alignment restrictions of storable types. -- -- Memory addresses are represented as values of type Ptr -- a, for some a which is an instance of class -- Storable. The type argument to Ptr helps provide some -- valuable type safety in FFI code (you can't mix pointers of different -- types without an explicit cast), while helping the Haskell type system -- figure out which marshalling method is needed for a given pointer. -- -- All marshalling between Haskell and a foreign language ultimately -- boils down to translating Haskell data structures into the binary -- representation of a corresponding data structure of the foreign -- language and vice versa. To code this marshalling in Haskell, it is -- necessary to manipulate primitive data types stored in unstructured -- memory blocks. The class Storable facilitates this manipulation -- on all types for which it is instantiated, which are the standard -- basic types of Haskell, the fixed size Int types -- (Int8, Int16, Int32, Int64), the fixed -- size Word types (Word8, Word16, Word32, -- Word64), StablePtr, all types from -- Foreign.C.Types, as well as Ptr. class Storable a -- | Read a value from the given memory location. -- -- Note that the peek and poke functions might require properly aligned -- addresses to function correctly. This is architecture dependent; thus, -- portable code should ensure that when peeking or poking values of some -- type a, the alignment constraint for a, as given by -- the function alignment is fulfilled. peek :: Storable a => Ptr a -> IO a -- | Write the given value to the given memory location. Alignment -- restrictions might apply; see peek. poke :: Storable a => Ptr a -> a -> IO ()