-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Regional memory pointers -- -- The library allows you to allocate memory in a region yielding a -- regional pointer to it. When the region terminates all pointers are -- automatically freed. Most importantly, a pointer can't be returned -- from the region. So it's impossible to reference unallocated memory. -- -- The primary technique used in this package is called "Lightweight -- monadic regions" which was invented by Oleg Kiselyov and Chung-chieh -- Shan. See: -- -- http://okmij.org/ftp/Haskell/regions.html#light-weight -- -- This technique is implemented in the regions package which is -- re-exported from this library. -- -- This library provides wrappers around all the Ptr functions -- from the Foreign.* modules from base. @package regional-pointers @version 0.3 -- | Unsafe functions for retrieving the actual Ptr from a -- regional pointer and for lifting operations on Ptrs to -- RegionalPtrs. -- -- These operations are unsafe because they allow you to free -- the regional pointer before exiting their region. So they enable you -- to perform IO with already freed pointers. module Foreign.Ptr.Region.Unsafe unsafePtr :: RegionalPtr α r -> Ptr α unsafeWrap :: (MonadIO m) => (Ptr α -> IO β) -> (RegionalPtr α r -> m β) unsafeWrap2 :: (MonadIO m) => (Ptr α -> γ -> IO β) -> (RegionalPtr α r -> γ -> m β) unsafeWrap3 :: (MonadIO m) => (Ptr α -> γ -> δ -> IO β) -> (RegionalPtr α r -> γ -> δ -> m β) module Foreign.Ptr.Region -- | A regional handle to memory. This should provide a safer replacement -- for Foreign.Ptr.Ptr data RegionalPtr α r :: (* -> *) -- | Construct a regional pointer from a native pointer and an IO -- computation that frees the pointer which is executed when the region -- exits. regionalPtr :: (MonadIO pr) => Ptr α -> CloseAction -> RegionT s pr (RegionalPtr α (RegionT s pr)) -- | The constant nullPtr contains a distinguished value of -- RegionalPtr that is not associated with a valid memory -- location. -- -- Note that nullPtr is a pure value. This means it does not -- perform the side-effect of registering a CloseAction like -- free nullPtr in the RegionT monad. nullPtr :: RegionalPtr α r -- | Apply a pure function to the inner pointer of a regional -- pointer. mapRegionalPtr :: (Ptr α -> Ptr β) -> (RegionalPtr α r -> RegionalPtr β r) -- | The castPtr function casts a pointer from one type to -- another. -- -- Wraps: Foreign.Ptr.castPtr castPtr :: RegionalPtr α r -> RegionalPtr β r -- | Advances the given address by the given offset in bytes. -- -- Wraps: Foreign.Ptr.plusPtr plusPtr :: RegionalPtr α r -> Int -> RegionalPtr β r -- | Given an arbitrary address and an alignment constraint, -- alignPtr yields the next higher address that fulfills the -- alignment constraint. An alignment constraint x is fulfilled -- by any address divisible by x. This operation is idempotent. -- -- Wraps: Foreign.Ptr.alignPtr alignPtr :: RegionalPtr α r -> Int -> RegionalPtr α r -- | Computes the offset required to get from the second to the first -- argument. We have -- -- 
--   p2 == p1 `plusPtr` (p2 `minusPtr` p1)
--
-- -- Wraps: Foreign.Ptr.minusPtr minusPtr :: RegionalPtr α r1 -> RegionalPtr β r2 -> Int module Foreign.Marshal.Alloc.Region -- | Convenience function which allocates sufficient memory to hold values -- of type α, applies the given continuation function to the -- resulting regional pointer and runs the resulting region. -- -- This should provide a safer replacement for: -- Foreign.Marshal.Alloc.alloca. -- -- Note that: alloca = allocaBytes $ sizeOf (undefined -- :: α) alloca :: (Storable α, MonadCatchIO pr) => (forall s. RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β -- | Convenience function which allocates the given number of bytes, -- applies the given continuation function to the resulting regional -- pointer and runs the resulting region. -- -- This should provide a safer replacement for: -- Foreign.Marshal.Alloc.allocaBytes. -- -- Note that: allocaBytes size f = runRegionT $ -- mallocBytes size >>= f allocaBytes :: (MonadCatchIO pr) => Int -> (forall s. RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β -- | Convenience function which allocates sufficient memory to hold values -- of type α and returns a regional pointer to them. -- -- This should provide a safer replacement for: -- Foreign.Marshal.Alloc.malloc. -- -- Note that: malloc = mallocBytes $ sizeOf (undefined -- :: α) malloc :: (Storable α, MonadCatchIO pr) => RegionT s pr (RegionalPtr α (RegionT s pr)) -- | Allocates the given number of bytes and returns a regional pointer to -- them. -- -- This should provide a safer replacement for: -- Foreign.Marshal.Alloc.mallocBytes. mallocBytes :: (MonadCatchIO pr) => Int -> RegionT s pr (RegionalPtr α (RegionT s pr)) -- | Lifts methods of the Storable type class from -- Foreign.Storable to regional pointers. module Foreign.Storable.Region -- | Read a value from a memory area regarded as an array of values of the -- same kind. The first argument specifies the start address of the array -- and the second the index into the array (the first element of the -- array has index 0). The following equality holds, -- -- 
--   peekElemOff addr idx = IOExts.fixIO $ \result ->
--     peek (addr `plusPtr` (idx * sizeOf result))
--
-- -- Note that this is only a specification, not necessarily the concrete -- implementation of the function. -- -- Wraps: Foreign.Storable.peekElemOff. peekElemOff :: (ParentOf pr cr, Storable α, MonadIO cr) => RegionalPtr α pr -> Int -> cr α -- | Write a value to a memory area regarded as an array of values of the -- same kind. The following equality holds: -- -- 
--   pokeElemOff addr idx x =
--     poke (addr `plusPtr` (idx * sizeOf x)) x
--
-- -- Wraps: Foreign.Storable.pokeElemOff. pokeElemOff :: (ParentOf pr cr, Storable α, MonadIO cr) => RegionalPtr α pr -> Int -> α -> cr () -- | Read a value from a memory location given by a base address and -- offset. The following equality holds: -- -- 
--   peekByteOff addr off = peek (addr `plusPtr` off)
--
-- -- Wraps: Foreign.Storable.peekByteOff. peekByteOff :: (ParentOf pr cr, Storable α, MonadIO cr) => RegionalPtr β pr -> Int -> cr α -- | Write a value to a memory location given by a base address and offset. -- The following equality holds: -- -- 
--   pokeByteOff addr off x = poke (addr `plusPtr` off) x
--
-- -- Wraps: Foreign.Storable.pokeByteOff. pokeByteOff :: (ParentOf pr cr, Storable α, MonadIO cr) => RegionalPtr β pr -> Int -> α -> cr () -- | 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. -- -- Wraps: Foreign.Storable.peek. peek :: (ParentOf pr cr, Storable α, MonadIO cr) => RegionalPtr α pr -> cr α -- | Write the given value to the given memory location. Alignment -- restrictions might apply; see peek. -- -- Wraps: Foreign.Storable.poke. poke :: (ParentOf pr cr, Storable α, MonadIO cr) => RegionalPtr α pr -> α -> cr () module Foreign.Marshal.Utils.Region -- | with val f executes the computation f, -- passing as argument a regional pointer to a temporarily allocated -- block of memory into which val has been marshalled (the -- combination of alloca and poke). -- -- The memory is freed when f terminates (either normally or via -- an exception). -- -- This provides a safer replacement for -- Foreign.Marshal.Utils.with. with :: (Storable α, MonadCatchIO pr) => α -> (forall s. RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β -- | Allocate a block of memory and marshal a value into it (the -- combination of malloc and poke). The size of the area -- allocated is determined by the sizeOf method from the instance -- of Storable for the appropriate type. -- -- This provides a safer replacement for -- Foreign.Marshal.Utils.new. new :: (Storable α, MonadCatchIO pr) => α -> RegionT s pr (RegionalPtr α (RegionT s pr)) -- | Convert a Haskell Bool to its numeric representation fromBool :: (Num a) => Bool -> a -- | Convert a Boolean in numeric representation to a Haskell value toBool :: (Num a) => a -> Bool -- | Copies the given number of bytes from the second area (source) into -- the first (destination); the copied areas may not overlap -- -- Wraps: Foreign.Marshal.Utils.copyBytes. copyBytes :: (ParentOf pr1 cr, ParentOf pr2 cr, MonadIO cr) => RegionalPtr α pr1 -> RegionalPtr α pr2 -> Int -> cr () -- | Copies the given number of bytes from the second area (source) into -- the first (destination); the copied areas may overlap -- -- Wraps: Foreign.Marshal.Utils.moveBytes. moveBytes :: (ParentOf pr1 cr, ParentOf pr2 cr, MonadIO cr) => RegionalPtr α pr1 -> RegionalPtr α pr2 -> Int -> cr () module Foreign.Marshal.Array.Region -- | Allocate storage for the given number of elements of a storable type. -- -- Like malloc, but for multiple elements. mallocArray :: (Storable α, MonadCatchIO pr) => Int -> RegionT s pr (RegionalPtr α (RegionT s pr)) -- | Like mallocArray, but add an extra position to hold a special -- termination element. mallocArray0 :: (Storable α, MonadCatchIO pr) => Int -> RegionT s pr (RegionalPtr α (RegionT s pr)) -- | Temporarily allocate space for the given number of elements (like -- alloca, but for multiple elements). allocaArray :: (Storable α, MonadCatchIO pr) => Int -> (forall s. RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β -- | Like allocaArray, but add an extra position to hold a special -- termination element. allocaArray0 :: (Storable α, MonadCatchIO pr) => Int -> (forall s. RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β -- | Convert an array of given length into a Haskell list. -- -- (This version traverses the array backwards using an accumulating -- parameter, which uses constant stack space. The previous version using -- mapM needed linear stack space.) -- -- Wraps: Foreign.Marshal.Array.peekArray. peekArray :: (Storable α, ParentOf pr cr, MonadIO cr) => Int -> RegionalPtr α pr -> cr [α] -- | Convert an array terminated by the given end marker into a Haskell -- list. -- -- Wraps: Foreign.Marshal.Array.peekArray0. peekArray0 :: (Storable α, Eq α, ParentOf pr cr, MonadIO cr) => α -> RegionalPtr α pr -> cr [α] -- | Write the list elements consecutive into memory. -- -- Wraps: Foreign.Marshal.Array.pokeArray. pokeArray :: (Storable α, ParentOf pr cr, MonadIO cr) => RegionalPtr α pr -> [α] -> cr () -- | Write the list elements consecutive into memory and terminate them -- with the given marker element. -- -- Wraps: Foreign.Marshal.Array.pokeArray0. pokeArray0 :: (Storable α, ParentOf pr cr, MonadIO cr) => α -> RegionalPtr α pr -> [α] -> cr () -- | Write a list of storable elements into a newly allocated, consecutive -- sequence of storable values. -- -- Like new, but for multiple elements. newArray :: (Storable α, MonadCatchIO pr) => [α] -> RegionT s pr (RegionalPtr α (RegionT s pr)) -- | Write a list of storable elements into a newly allocated, consecutive -- sequence of storable values, where the end is fixed by the given end -- marker. newArray0 :: (Storable α, MonadCatchIO pr) => α -> [α] -> RegionT s pr (RegionalPtr α (RegionT s pr)) -- | Temporarily store a list of storable values in memory. -- -- Like with, but for multiple elements. withArray :: (Storable α, MonadCatchIO pr) => [α] -> (forall s. RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β -- | Like withArray, but a terminator indicates where the array -- ends. withArray0 :: (Storable α, MonadCatchIO pr) => α -> [α] -> (forall s. RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β -- | Like withArray, but the action gets the number of values as an -- additional parameter. withArrayLen :: (Storable α, MonadCatchIO pr) => [α] -> (forall s. Int -> RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β -- | Like withArrayLen, but a terminator indicates where the array -- ends. withArrayLen0 :: (Storable α, MonadCatchIO pr) => α -> [α] -> (forall s. Int -> RegionalPtr α (RegionT s pr) -> RegionT s pr β) -> pr β -- | Copy the given number of elements from the second array (source) into -- the first array (destination); the copied areas may not -- overlap. -- -- Wraps: Foreign.Marshal.Array.copyArray. copyArray :: (Storable α, ParentOf pr1 cr, ParentOf pr2 cr, MonadIO cr) => RegionalPtr α pr1 -> RegionalPtr α pr2 -> Int -> cr () -- | Copy the given number of elements from the second array (source) into -- the first array (destination); the copied areas may overlap. -- -- Wraps: Foreign.Marshal.Array.moveArray. moveArray :: (Storable α, ParentOf pr1 cr, ParentOf pr2 cr, MonadIO cr) => RegionalPtr α pr1 -> RegionalPtr α pr1 -> Int -> cr () -- | Return the number of elements in an array, excluding the terminator. -- -- Wraps: Foreign.Marshal.Array.lengthArray0. lengthArray0 :: (Storable α, Eq α, ParentOf pr cr, MonadIO cr) => α -> RegionalPtr α pr -> cr Int -- | Advance a pointer into an array by the given number of elements. -- -- Wraps: Foreign.Marshal.Array.advancePtr. advancePtr :: (Storable α) => RegionalPtr α pr -> Int -> RegionalPtr α pr -- | Lifts functions and types from Foreign.C.String to regional -- pointers. module Foreign.C.String.Region -- | Handy type synonym for a regional pointer to an array of C characters -- terminated by a NUL. -- -- This should provide a safer replacement for -- Foreign.C.String.CString. type RegionalCString r = RegionalPtr CChar r -- | Handy type synonym for a regional pointer to an array of C characters -- which is paired with the length of the array instead of terminated by -- a NUL. (Thus allowing NUL characters in the middle of the string) -- -- This should provide a safer replacement for -- Foreign.C.String.CStringLen. type RegionalCStringLen r = (RegionalPtr CChar r, Int) -- | Marshal a NUL terminated C string into a Haskell string. -- -- Wraps: Foreign.C.String.peekCString peekCString :: (ParentOf pr cr, MonadIO cr) => RegionalCString pr -> cr String -- | Marshal a C string with explicit length into a Haskell string. -- -- Wraps: Foreign.C.String.peekCStringLen. peekCStringLen :: (ParentOf pr cr, MonadIO cr) => RegionalCStringLen pr -> cr String -- | Marshal a Haskell string into a NUL terminated C string. -- -- The Haskell string may not contain any NUL characters -- -- Wraps: Foreign.C.String.newCString. newCString :: (MonadCatchIO pr) => String -> RegionT s pr (RegionalCString (RegionT s pr)) -- | Marshal a Haskell string into a C string (ie, character array) with -- explicit length information. -- -- Wraps: Foreign.C.String.newCStringLen. newCStringLen :: (MonadCatchIO pr) => String -> RegionT s pr (RegionalCStringLen (RegionT s pr)) -- | Marshal a Haskell string into a NUL terminated C string using -- temporary storage. -- -- -- -- Wraps: Foreign.C.String.withCString. withCString :: (MonadCatchIO pr) => String -> (forall s. RegionalCString (RegionT s pr) -> RegionT s pr α) -> pr α -- | Marshal a Haskell string into a C string (ie, character array) in -- temporary storage, with explicit length information. -- -- -- -- Wraps: Foreign.C.String.withCStringLen. withCStringLen :: (MonadCatchIO pr) => String -> (forall s. RegionalCStringLen (RegionT s pr) -> RegionT s pr α) -> pr α -- | Generalizes Foreign.C.String.charIsRepresentable to -- any MonadIO. charIsRepresentable :: (MonadIO m) => Char -> m Bool -- | Convert a Haskell character to a C character. This function is only -- safe on the first 256 characters. castCharToCChar :: Char -> CChar -- | Convert a C byte, representing a Latin-1 character, to the -- corresponding Haskell character. castCCharToChar :: CChar -> Char -- | Marshal a NUL terminated C string into a Haskell string. -- -- Wraps: Foreign.C.String.peekCAString. peekCAString :: (ParentOf pr cr, MonadIO cr) => RegionalCString pr -> cr String -- | Marshal a C string with explicit length into a Haskell string. -- -- Wraps: Foreign.C.String.peekCAStringLen. peekCAStringLen :: (ParentOf pr cr, MonadIO cr) => RegionalCStringLen pr -> cr String -- | Marshal a Haskell string into a NUL terminated C string. -- -- The Haskell string may not contain any NUL characters -- -- Wraps: Foreign.C.String.newCAString. newCAString :: (MonadCatchIO pr) => String -> RegionT s pr (RegionalCString (RegionT s pr)) -- | Marshal a Haskell string into a C string (ie, character array) with -- explicit length information. -- -- Wraps: Foreign.C.String.newCAStringLen. newCAStringLen :: (MonadCatchIO pr) => String -> RegionT s pr (RegionalCStringLen (RegionT s pr)) -- | Marshal a Haskell string into a NUL terminated C string using -- temporary storage. -- -- -- -- Wraps: Foreign.C.String.withCAString. withCAString :: (MonadCatchIO pr) => String -> (forall s. RegionalCString (RegionT s pr) -> RegionT s pr α) -> pr α -- | Marshal a Haskell string into a C string (ie, character array) in -- temporary storage, with explicit length information. -- -- -- -- Wraps: Foreign.C.String.withCAStringLen. withCAStringLen :: (MonadCatchIO pr) => String -> (forall s. RegionalCStringLen (RegionT s pr) -> RegionT s pr α) -> pr α -- | Handy type synonym for a regional pointer to an array of C wide -- characters terminated by a NUL. -- -- This should provide a safer replacement for -- Foreign.C.String.CWString. type RegionalCWString r = RegionalPtr CWchar r -- | Handy type synonym for a regional pointer to an array of C wide -- characters which is paired with the length of the array instead of -- terminated by a NUL. (Thus allowing NUL characters in the middle of -- the string) -- -- This should provide a safer replacement for -- Foreign.C.String.CWStringLen. type RegionalCWStringLen r = (RegionalPtr CWchar r, Int) -- | Marshal a NUL terminated C wide string into a Haskell string. -- -- Wraps: Foreign.C.String.peekCWString. peekCWString :: (ParentOf pr cr, MonadIO cr) => RegionalCWString pr -> cr String -- | Marshal a C wide string with explicit length into a Haskell string. -- -- Wraps: Foreign.C.String.peekCWStringLen. peekCWStringLen :: (ParentOf pr cr, MonadIO cr) => RegionalCWStringLen pr -> cr String -- | Marshal a Haskell string into a NUL terminated C wide string. -- -- The Haskell string may not contain any NUL characters. -- -- Wraps: Foreign.C.String.newCWString. newCWString :: (MonadCatchIO pr) => String -> RegionT s pr (RegionalCWString (RegionT s pr)) -- | Marshal a Haskell string into a C wide string (ie, wide character -- array) with explicit length information. -- -- Wraps: Foreign.C.String.newCWStringLen. newCWStringLen :: (MonadCatchIO pr) => String -> RegionT s pr (RegionalCWStringLen (RegionT s pr)) -- | Marshal a Haskell string into a NUL terminated C wide string using -- temporary storage. -- -- -- -- Wraps: Foreign.C.String.withCWString. withCWString :: (MonadCatchIO pr) => String -> (forall s. RegionalCWString (RegionT s pr) -> RegionT s pr α) -> pr α -- | Marshal a Haskell string into a NUL terminated C wide string using -- temporary storage. -- -- -- -- Wraps: Foreign.C.String.withCWStringLen. withCWStringLen :: (MonadCatchIO pr) => String -> (forall s. RegionalCWStringLen (RegionT s pr) -> RegionT s pr α) -> pr α