Copyright | (c) Alexey Kuleshevich 2020 |
---|---|
License | BSD3 |
Maintainer | Alexey Kuleshevich <alexey@kuleshevi.ch> |
Stability | experimental |
Portability | non-portable |
Safe Haskell | None |
Language | Haskell2010 |
Synopsis
- module Data.Prim
- data Pinned
- data Bytes (p :: Pinned)
- class MemRead mr
- countMem :: forall e mr. (MemRead mr, Prim e) => mr -> Count e
- countRemMem :: forall e mr. (MemRead mr, Prim e) => mr -> (Count e, Count Word8)
- byteCountMem :: MemRead mr => mr -> Count Word8
- indexOffMem :: (MemRead mr, Prim e) => mr -> Off e -> e
- indexByteOffMem :: (MemRead mr, Prim e) => mr -> Off Word8 -> e
- emptyMem :: forall ma. MemAlloc ma => FrozenMem ma
- singletonMem :: forall e ma. (MemAlloc ma, Prim e) => e -> FrozenMem ma
- cycleMemN :: forall ma mr. (MemAlloc ma, MemRead mr) => Int -> mr -> FrozenMem ma
- createMemST :: forall e b ma. (MemAlloc ma, Prim e) => Count e -> (forall s. ma s -> ST s b) -> (b, FrozenMem ma)
- createMemST_ :: (MemAlloc ma, Prim e) => Count e -> (forall s. ma s -> ST s b) -> FrozenMem ma
- createZeroMemST :: forall e ma b. (MemAlloc ma, Prim e) => Count e -> (forall s. ma s -> ST s b) -> (b, FrozenMem ma)
- createZeroMemST_ :: forall e ma b. (MemAlloc ma, Prim e) => Count e -> (forall s. ma s -> ST s b) -> FrozenMem ma
- cloneMem :: forall ma. MemAlloc ma => FrozenMem ma -> FrozenMem ma
- copyMem :: (MonadPrim s m, MemRead mr, MemWrite mw, Prim e) => mr -> Off e -> mw s -> Off e -> Count e -> m ()
- copyByteOffMem :: (MemWrite mw, MonadPrim s m, MemRead mr, Prim e) => mr -> Off Word8 -> mw s -> Off Word8 -> Count e -> m ()
- copyByteOffToMBytesMem :: (MemRead mr, MonadPrim s m, Prim e) => mr -> Off Word8 -> MBytes p s -> Off Word8 -> Count e -> m ()
- copyByteOffToPtrMem :: (MemRead mr, MonadPrim s m, Prim e) => mr -> Off Word8 -> Ptr e -> Off Word8 -> Count e -> m ()
- eqMem :: (MemRead mr1, MemRead mr2) => mr1 -> mr2 -> Bool
- compareMem :: forall e mr1 mr2. (MemRead mr1, MemRead mr2, Prim e) => mr1 -> Off e -> mr2 -> Off e -> Count e -> Ordering
- compareByteOffMem :: (MemRead mr, MemRead mr', Prim e) => mr' -> Off Word8 -> mr -> Off Word8 -> Count e -> Ordering
- compareByteOffToPtrMem :: (MemRead mr, MonadPrim s m, Prim e) => mr -> Off Word8 -> Ptr e -> Off Word8 -> Count e -> m Ordering
- compareByteOffToBytesMem :: (MemRead mr, Prim e) => mr -> Off Word8 -> Bytes p -> Off Word8 -> Count e -> Ordering
- convertMem :: (MemRead mr, MemAlloc ma) => mr -> FrozenMem ma
- toListMem :: forall e mr. (MemRead mr, Prim e) => mr -> [e]
- toListSlackMem :: forall e mr. (MemRead mr, Prim e) => mr -> ([e], [Word8])
- toByteListMem :: forall ma. MemAlloc ma => FrozenMem ma -> [Word8]
- foldrCountMem :: forall e b mr. (MemRead mr, Prim e) => Count e -> (e -> b -> b) -> b -> mr -> b
- showsHexMem :: MemRead mr => mr -> [ShowS]
- fromListMem :: forall e ma. (Prim e, MemAlloc ma) => [e] -> FrozenMem ma
- fromByteListMem :: forall ma. MemAlloc ma => [Word8] -> FrozenMem ma
- fromListMemN :: forall e ma. (Prim e, MemAlloc ma) => Count e -> [e] -> (Either [e] (Count e), FrozenMem ma)
- fromListZeroMemN :: forall e ma. (Prim e, MemAlloc ma) => Count e -> [e] -> (Either [e] (Count e), FrozenMem ma)
- fromListZeroMemN_ :: forall e ma. (Prim e, MemAlloc ma) => Count e -> [e] -> FrozenMem ma
- data MBytes (p :: Pinned) s
- class MemWrite mw
- class (MemRead (FrozenMem ma), MemWrite ma) => MemAlloc ma where
- newtype MemState a s = MemState {
- unMemState :: a
- getCountMem :: forall e ma m s. (MemAlloc ma, MonadPrim s m, Prim e) => ma s -> m (Count e)
- getCountRemMem :: forall e ma m s. (MemAlloc ma, MonadPrim s m, Prim e) => ma s -> m (Count e, Count Word8)
- getByteCountMem :: (MemAlloc ma, MonadPrim s m) => ma s -> m (Count Word8)
- readOffMem :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off e -> m e
- readByteOffMem :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off Word8 -> m e
- writeOffMem :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off e -> e -> m ()
- writeByteOffMem :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off Word8 -> e -> m ()
- setMem :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off e -> Count e -> e -> m ()
- modifyFetchOldMem :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off e -> (e -> e) -> m e
- modifyFetchOldMemM :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off e -> (e -> m e) -> m e
- modifyFetchNewMem :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off e -> (e -> e) -> m e
- modifyFetchNewMemM :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off e -> (e -> m e) -> m e
- allocMem :: (MemAlloc ma, Prim e, MonadPrim s m) => Count e -> m (ma s)
- allocZeroMem :: forall e ma m s. (MemAlloc ma, MonadPrim s m, Prim e) => Count e -> m (ma s)
- thawMem :: (MemAlloc ma, MonadPrim s m) => FrozenMem ma -> m (ma s)
- thawCloneMem :: forall mr ma m s. (MemRead mr, MemAlloc ma, MonadPrim s m) => mr -> m (ma s)
- thawCopyMem :: forall e mr ma m s. (Prim e, MemRead mr, MemAlloc ma, MonadPrim s m) => mr -> Off e -> Count e -> m (ma s)
- freezeMem :: (MemAlloc ma, MonadPrim s m) => ma s -> m (FrozenMem ma)
- freezeCloneMem :: forall ma m s. (MemAlloc ma, MonadPrim s m) => ma s -> m (FrozenMem ma)
- freezeCopyMem :: forall e ma m s. (Prim e, MemAlloc ma, MonadPrim s m) => ma s -> Off e -> Count e -> m (FrozenMem ma)
- resizeMem :: (MemAlloc ma, MonadPrim s m, Prim e) => ma s -> Count e -> m (ma s)
- withScrubbedMem :: forall e ma m a. (MonadUnliftPrim RW m, Prim e, MemAlloc ma, PtrAccess RW (ma RW)) => Count e -> (ma RW -> m a) -> m a
- moveMem :: (MonadPrim s m, MemWrite mw1, MemWrite mw2, Prim e) => mw1 s -> Off e -> mw2 s -> Off e -> Count e -> m ()
- moveByteOffMem :: (MemWrite mw, MonadPrim s m, MemWrite mw', Prim e) => mw' s -> Off Word8 -> mw s -> Off Word8 -> Count e -> m ()
- moveByteOffToMBytesMem :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off Word8 -> MBytes p s -> Off Word8 -> Count e -> m ()
- moveByteOffToPtrMem :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off Word8 -> Ptr e -> Off Word8 -> Count e -> m ()
- loadListMem :: forall e ma m s. (Prim e, MemAlloc ma, MonadPrim s m) => [e] -> ma s -> m ([e], Count e)
- loadListMem_ :: forall e ma m s. (Prim e, MemAlloc ma, MonadPrim s m) => [e] -> ma s -> m ()
- loadListMemN :: forall e mw m s. (MemWrite mw, MonadPrim s m, Prim e) => Count e -> [e] -> mw s -> m ([e], Count e)
- loadListMemN_ :: forall e mw m s. (Prim e, MemWrite mw, MonadPrim s m) => Count e -> [e] -> mw s -> m ()
- loadListOffMem :: forall e ma m s. (Prim e, MemAlloc ma, MonadPrim s m) => [e] -> ma s -> Off e -> m ([e], Count e)
- loadListOffMemN :: (MemWrite mw, MonadPrim s m, Prim e) => Count e -> [e] -> mw s -> Off e -> m ([e], Count e)
- loadListByteOffMem :: (MemAlloc ma, MonadPrim s m, Prim e) => [e] -> ma s -> Off Word8 -> m ([e], Count e)
- loadListByteOffMemN :: (MemWrite mw, MonadPrim s m, Prim e) => Count e -> [e] -> mw s -> Off Word8 -> m ([e], Count e)
Documentation
module Data.Prim
In GHC there is a distinction between pinned and unpinned memory.
Pinned memory is such that when allocated, it is guaranteed not to move throughout the
lifetime of a program. In other words the address pointer that refers to allocated
bytes will not change until the associated ByteArray#
or MutableByteArray#
is no
longer referenced anywhere in the program at which point it gets garbage collected. On
the other hand unpinned memory can be moved around during GC, which helps to reduce
memory fragmentation.
Pinned/unpinnned choice during allocation is a bit of a lie, because when attempt is
made to allocate memory as unpinned, but requested size is a bit more than a certain
threshold (somewhere around 3KiB) it might still be allocated as pinned. Because of
that fact through out the "primal" universe there is a distinction between memory that
is either
or Pin
ned
.Inc
onclusive
It is possible to use one of toPinnedBytes
or
toPinnedMBytes
to get a conclusive type.
Since: 0.1.0
Immutable
data Bytes (p :: Pinned) Source #
An immutable region of memory which was allocated either as pinned or unpinned.
Constructor is not exported for safety. Violating type level Pinned
kind is very
dangerous. Type safe constructor fromByteArray#
and unwrapper
toByteArray#
should be used instead. As a backdoor, of course,
the actual constructor is available from Data.Prim.Memory.Internal
Instances
Type class that can be implemented for an immutable data type that provides read-only direct access to memory
byteCountMem, indexByteOffMem, copyByteOffToMBytesMem, copyByteOffToPtrMem, compareByteOffToPtrMem, compareByteOffToBytesMem, compareByteOffMem
Instances
Size
countMem :: forall e mr. (MemRead mr, Prim e) => mr -> Count e Source #
Figure out how many elements fits into the immutable region of memory. It is
possible that there is a remainder of bytes left, see countRemMem
for getting that
too.
Examples
>>>
b = fromListMem [0 .. 5 :: Word8] :: Bytes 'Pin
>>>
b
[0x00,0x01,0x02,0x03,0x04,0x05]>>>
countMem b :: Count Word16
Count {unCount = 3}>>>
countMem b :: Count Word32
Count {unCount = 1}
Since: 0.1.0
countRemMem :: forall e mr. (MemRead mr, Prim e) => mr -> (Count e, Count Word8) Source #
Compute how many elements and a byte size remainder that can fit into the region of memory.
Examples
>>>
b = fromListMem [0 .. 5 :: Word8] :: Bytes 'Pin
>>>
b
[0x00,0x01,0x02,0x03,0x04,0x05]>>>
countRemMem @Word16 b
(Count {unCount = 3},Count {unCount = 0})>>>
countRemMem @Word32 b
(Count {unCount = 1},Count {unCount = 2})
Since: 0.1.0
byteCountMem :: MemRead mr => mr -> Count Word8 Source #
Number of bytes allocated by the data type available for reading.
Example
>>>
:set -XDataKinds
>>>
import Data.Prim.Memory
>>>
byteCountMem (fromByteListMem [1,2,3] :: Bytes 'Inc)
Count {unCount = 3}
Since: 0.1.0
Index
:: (MemRead mr, Prim e) | |
=> mr | memRead - Memory to read an element from |
-> Off e | off - Offset in number of elements from the beginning of Preconditions: 0 <= off unOffBytes off <= unCount (byteCountMem memRead - byteCountType @e) |
-> e |
Read an element with an offset in number of elements, rather than bytes as is the
case with indexByteOffMem
.
- Unsafe
- Bounds are not checked. When precondition for
off
argument is violated the result is either unpredictable output or failure with a segfault.
Since: 0.1.0
:: (MemRead mr, Prim e) | |
=> mr | memRead - Memory to read an element from |
-> Off Word8 | off - Offset in number of elements from the beginning of Preconditions: 0 <= unOff off unOff off <= unCount (byteCountMem memRead - byteCountType @e) |
-> e |
Read an element with an offset in number of bytes. Bounds are not checked.
- Unsafe
- When precondition for
off
argument is violated the result is either unpredictable output or failure with a segfault.
Since: 0.1.0
Construct
:: (MemAlloc ma, Prim e) | |
=> e | The single element that will be stored in the newly allocated region of memory |
-> FrozenMem ma |
Allocate a region of immutable memory that holds a single element.
Example
>>>
:set -XTypeApplications
>>>
:set -XDataKinds
>>>
import Data.Prim.Memory
>>>
toListMem (singletonMem @Word16 @(MBytes 'Inc) 0xffff) :: [Word8]
[255,255]
Since: 0.1.0
cycleMemN :: forall ma mr. (MemAlloc ma, MemRead mr) => Int -> mr -> FrozenMem ma Source #
Place n
copies of supplied region of memory one after another in a newly allocated
contiguous chunk of memory. Similar to stimes
, but the source memory memRead
does
not have to match the type of FrozenMem
ma.
Example
>>>
:set -XTypeApplications
>>>
:set -XDataKinds
>>>
import Data.Prim.Memory
>>>
let b = fromListMem @Word8 @(MBytes 'Inc) [0xde, 0xad, 0xbe, 0xef]
>>>
cycleMemN @(MBytes 'Inc) 2 b
[0xde,0xad,0xbe,0xef,0xde,0xad,0xbe,0xef]
Since: 0.1.0
createMemST :: forall e b ma. (MemAlloc ma, Prim e) => Count e -> (forall s. ma s -> ST s b) -> (b, FrozenMem ma) Source #
createZeroMemST :: forall e ma b. (MemAlloc ma, Prim e) => Count e -> (forall s. ma s -> ST s b) -> (b, FrozenMem ma) Source #
:: (MemAlloc ma, Prim e) | |
=> Count e | memCount - Size of the newly allocated memory region in number of elements of
type Precoditions: Size should be non-negative, but smaller than amount of available memory. Note that the second condition simply describes overflow. 0 <= memCount Possibility of overflow: unCount memCount <= fromByteCount @e (Count maxBound) |
-> (forall s. ma s -> ST s b) | fillAction -- Action that will be used to modify contents of newly allocated memory. It is not required to overwrite the full region, since it was reset to zeros right after allocation. |
-> FrozenMem ma |
Same as createMemST_
, except it ensures that the memory gets reset with zeros prior
to applying the ST
filling action fillAction
.
- Unsafe
- Same reasons as
allocZeroMem
: violation of precondition formemCount
may result in undefined behavior orHeapOverflow
async exception.
Example
Note that this example will work correctly only on little-endian machines:
>>>
:set -XTypeApplications
>>>
import Data.Prim
>>>
import Control.Monad
>>>
let ibs = zip [0, 4 ..] [0x48,0x61,0x73,0x6b,0x65,0x6c,0x6c] :: [(Off Word8, Word8)]
>>>
let c = Count (length ibs) :: Count Char
>>>
let bc = createZeroMemST_ @_ @(MBytes 'Inc) c $ \m -> forM_ ibs $ \(i, b) -> writeByteOffMem m i b
>>>
toListMem bc :: String
"Haskell"
Since: 0.1.0
Copy
Copy all of the data from the source into a newly allocate memory region of identical size.
Examples
>>>
:set -XDataKinds
>>>
import Data.Prim.Memory
>>>
let xs = fromByteListMem @(MBytes 'Pin) [0..15] :: Bytes 'Pin
>>>
let ys = cloneMem xs
>>>
let report bEq pEq = print $ "Bytes equal: " ++ show bEq ++ ", their pointers equal: " ++ show pEq
>>>
withPtrBytes xs $ \ xsPtr -> withPtrBytes ys $ \ ysPtr -> report (xs == ys) (xsPtr == ysPtr)
"Bytes equal: True, their pointers equal: False"
Since: 0.2.0
:: (MonadPrim s m, MemRead mr, MemWrite mw, Prim e) | |
=> mr | memSourceRead - Read-only source memory region from where to copy |
-> Off e | memSourceOff - Offset into source memory in number of elements of type Preconditions: 0 <= memSourceOff unOff memSourceOff < unCount (countMem memSourceRead) |
-> mw s | memTargetWrite - Target mutable memory |
-> Off e | memTargetOff - Offset into target memory in number of elements Preconditions: 0 <= memTargetOff With offset applied it should still refer to the same memory region. For types that
also implement targetCount <- getCountMem memTargetWrite unOff memTargetOff < unCount targetCount |
-> Count e | memCount - Number of elements of type Preconditions: 0 <= memCount Both source and target memory regions must have enough memory to perform a copy
of unOff memSourceOff + unCount memCount < unCount (countMem memSourceRead) and for targetCount <- getCountMem memTargetWrite unOff memTargetOff + unCount memCount < unCount targetCount |
-> m () |
Similar to copyByteOffMem
, but supply offsets in number of elements instead of
bytes. Copy contiguous chunk of memory from the read only memory region into the target
mutable memory region. Source and target must not refer to the same memory region,
otherwise that would imply that the source is not immutable which would be a violation
of some other invariant elsewhere in the code.
- Unsafe
- When any precondition for one of the offsets
memSourceOff
,memTargetOff
or the element countmemCount
is violated a call to this function can result in: copy of data that doesn't belong tomemSourceRead
, heap corruption or failure with a segfault.
Since: 0.1.0
:: (MemWrite mw, MonadPrim s m, MemRead mr, Prim e) | |
=> mr | memSourceRead - Read-only source memory region from where to copy |
-> Off Word8 | memSourceOff - Offset into source memory in number of bytes Preconditions: 0 <= memSourceOff unOff memSourceOff <= unCount (byteCountMem memSourceRead - byteCountType @e) |
-> mw s | memTargetWrite - Target mutable memory |
-> Off Word8 | memTargetOff - Offset into target memory in number of bytes Preconditions: 0 <= memTargetOff With offset applied it should still refer to the same memory region. For types that
also implement targetByteCount <- getByteCountMem memTargetWrite unOffBytes memTargetOff <= unCount (targetByteCount - byteCountType @e) |
-> Count e | memCount - Number of elements of type Preconditions: 0 <= memCount Both source and target memory regions must have enough memory to perform a copy
of unOff memSourceOff + unCountBytes memCount <= unCount (byteCountMem memSourceRead - byteCountType @e) and for targetByteCount <- getByteCountMem memTargetWrite unOff memTargetOff + unCountBytes memCount <= unCount (targetByteCount - byteCountType @e) |
-> m () |
Copy contiguous chunk of memory from the read only memory region into the target mutable memory region. Source and target must not refer to the same memory region, otherwise that would imply that the source is not immutable which would be a violation of some other invariant elsewhere in the code.
- Unsafe
- When any precondition for one of the offsets
memSourceOff
,memTargetOff
or the element countmemCount
is violated a call to this function can result in: copy of data that doesn't belong tomemSourceRead
, heap corruption or failure with a segfault.
Since: 0.1.0
copyByteOffToMBytesMem Source #
:: (MemRead mr, MonadPrim s m, Prim e) | |
=> mr | memSourceRead - Source from where to copy |
-> Off Word8 | memSourceOff - Offset into source memory in number of bytes Preconditions: 0 <= memSourceOff unOff memSourceOff <= unCount (byteCountMem memSourceRead - byteCountType @e) |
-> MBytes p s | memTargetWrite - Target mutable memory |
-> Off Word8 | memTargetOff - Offset into target memory in number of bytes Preconditions: 0 <= memTargetOff unOff memTargetOff <= unCount (byteCountMem memTargetWrite - byteCountType @e) |
-> Count e | memCount - Number of elements of type Preconditions: 0 <= memCount unCountBytes memCount + unOff memSourceOff <= unCount (byteCountMem memSourceRead - byteCountType @e) unCountBytes memCount + unOff memTargetOff <= unCount (byteCountMem memTargetRead - byteCountType @e) |
-> m () |
Copy contiguous chunk of memory from the read only memory into the target mutable
MBytes
. Source and target must not refer to the same memory region, otherwise
that would imply that the source is not immutable which would be a violation of some
other invariant elsewhere in the code.
- Unsafe
- When a precondition for either of the offsets
memSourceOff
,memTargetOff
or the element countmemCount
is violated the result is either unpredictable output or failure with a segfault.
Since: 0.1.0
:: (MemRead mr, MonadPrim s m, Prim e) | |
=> mr | memSourceRead - Source from where to copy |
-> Off Word8 | memSourceOff - Offset into source memory in number of bytes Preconditions: 0 <= memSourceOff unOff memSourceOff <= unCount (byteCountMem memSourceRead - byteCountType @e) |
-> Ptr e | memTargetWrite - Pointer to the target mutable memory Preconditions: Once the pointer is advanced by |
-> Off Word8 | memTargetOff - Number of bytes to advance the pointer Precondition: Once the pointer is advanced by |
-> Count e | memCount - Number of elements of type Preconditions: 0 <= memCount unCountBytes memCount + unOff memSourceOff <= unCount (byteCountMem memSourceRead - byteCountType @e) |
-> m () |
Copy contiguous chunk of memory from the read only memory into the target mutable
Ptr
. Source and target must not refer to the same memory region, otherwise that
would imply that the source is not immutable which would be a violation of some other
invariant elsewhere in the code.
- Unsafe
- When any precondition for one of the offsets
memSourceOff
,memTargetOff
or the element countmemCount
is violated a call to this function can result in: copy of data that doesn't belong tomemSourceRead
, heap corruption or failure with a segfault.
Since: 0.1.0
Compare
eqMem :: (MemRead mr1, MemRead mr2) => mr1 -> mr2 -> Bool Source #
Compare two memory regions byte-by-byte. False
is returned immediately when sizes
reported by byteCountMem
do not match. Computation may be short-circuited on the
first mismatch, but it is MemRead
implementation specific.
Since: 0.1.0
:: (MemRead mr1, MemRead mr2, Prim e) | |
=> mr1 | First region of memory |
-> Off e | Offset in number of elements into the first region |
-> mr2 | Second region of memory |
-> Off e | Offset in number of elements into the second region |
-> Count e | Number of elements to compare |
-> Ordering |
Compare two regions of memory byte-by-byte. It will return EQ
whenever both regions
are exactly the same and LT
or GT
as soon as the first byte is reached that is less
than or greater than respectfully in the first region when compared to the second
one. It is safe for both regions to refer to the same part of memory, since this is a
pure function and both regions of memory are read-only.
:: (MemRead mr, MemRead mr', Prim e) | |
=> mr' | memRead1 - First memory region |
-> Off Word8 | memOff1 - Offset for Preconditions: 0 <= memOff1 unOff memOff1 <= unCount (byteCountMem memRead1 - byteCountType @e) |
-> mr | memRead2 - Second memory region |
-> Off Word8 | memOff2 - Offset for Preconditions: 0 <= memOff2 unOff memOff2 <= unCount (byteCountMem memRead2 - byteCountType @e) |
-> Count e | memCount - Number of elements of type Preconditions: 0 <= memCount unCountBytes memCount + unOff memOff1 <= unCount (byteCountMem memRead1 - byteCountType @e) unCountBytes memCount + unOff memOff2 <= unCount (byteCountMem memRead2 - byteCountType @e) |
-> Ordering |
Compare two read-only regions of memory byte-by-byte. The very first mismatched
byte will cause this function to produce LT
if the byte in memRead1
is smaller
than the one in memRead2
and GT
if it is bigger. It is not a requirement to
short-circuit on the first mismatch, but it is a good optimization to have for
non-sensitive data. Memory regions that store security critical data may choose to
implement this function to work in constant time.
This function is usually implemented by either one of compareByteOffToPtrMem
or
compareByteOffToBytesMem
, depending on the nature of mr
type. However it differs
from the aforementioned functions with a fact that it is pure non-monadic
computation.
- Unsafe
- When any precondition for either of the offsets
memOff1
,memOff2
or the element countmemCount
is violated the result is either unpredictable output or failure with a segfault.
Since: 0.1.0
compareByteOffToPtrMem Source #
:: (MemRead mr, MonadPrim s m, Prim e) | |
=> mr | memRead1 - First memory region |
-> Off Word8 | memOff1 - Offset for Preconditions: 0 <= memOff1 unOff memOff1 <= unCount (byteCountMem memRead1 - byteCountType @e) |
-> Ptr e | memRead2- Second memory region that can be accessed by a pointer Preconditions Once the pointer is advanced by |
-> Off Word8 | memOff2 - Number of bytes to advance the pointer Precondition: Once the pointer is advanced by |
-> Count e | memCount - Number of elements of type Preconditions: 0 <= memCount unCountBytes memCount + unOff memOff1 <= unCount (byteCountMem memRead1 - byteCountType @e) |
-> m Ordering |
Same as compareByteOffMem
, but compare the read-only
memory region to a region addressed by a Ptr
inside of a MonadPrim
.
- Unsafe
- When any precondition for either of the offsets
memOff1
,memOff2
, the pointermemRead2
or the element countmemCount
is violated the result is either unpredictable output or failure with a segfault.
Since: 0.1.0
compareByteOffToBytesMem Source #
:: (MemRead mr, Prim e) | |
=> mr | memRead1 - First memory region |
-> Off Word8 | memOff1 - Offset for Preconditions: 0 <= memOff1 unOff memOff1 <= unCount (byteCountMem memRead1 - byteCountType @e) |
-> Bytes p | memRead2- Second memory region that is backed by |
-> Off Word8 | memOff2 - Offset for Preconditions: 0 <= memOff2 unOff memOff2 <= unCount (byteCountMem memRead2 - byteCountType @e) |
-> Count e | memCount - Number of elements of type Preconditions: 0 <= memCount unCountBytes memCount + unOff memOff1 <= unCount (byteCountMem memRead1 - byteCountType @e) unCountBytes memCount + unOff memOff2 <= unCount (byteCountMem memRead2 - byteCountType @e) |
-> Ordering |
Same as compareByteOffMem
, but compare the read-only memory region to Bytes
.
- Unsafe
- When any precondition for either of the offsets
memOff1
,memOff2
or the element countmemCount
is violated the result is either unpredictable output or failure with a segfault.
Since: 0.1.0
Convert
convertMem :: (MemRead mr, MemAlloc ma) => mr -> FrozenMem ma Source #
O(n) - Convert a read-only memory region into a newly allocated other type of memory region
>>>
import Data.ByteString (pack)
>>>
bs = pack [0x10 .. 0x20]
>>>
bs
"\DLE\DC1\DC2\DC3\DC4\NAK\SYN\ETB\CAN\EM\SUB\ESC\FS\GS\RS\US ">>>
convertMem bs :: Bytes 'Inc
[0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1a,0x1b,0x1c,0x1d,0x1e,0x1f,0x20]
Since: 0.1.0
To list
toListMem :: forall e mr. (MemRead mr, Prim e) => mr -> [e] Source #
Convert an immutable memory region to a list. Whenever memory byte count is not
exactly divisible by the size of the element there will be some slack left unaccounted
for. In order to get a hold of this slack use toListSlackMem
instead.
Examples
>>>
import Data.Prim.Memory
>>>
import Numeric (showHex)
>>>
let b = fromByteListMem [0x48,0x61,0x73,0x6b,0x65,0x6c,0x6c] :: Bytes 'Inc
>>>
toListMem b :: [Int8]
[72,97,115,107,101,108,108]>>>
let xs = toListMem b :: [Word32]
>>>
xs
[1802723656]>>>
showHex (head xs) ""
"6b736148"
Since: 0.1.0
toListSlackMem :: forall e mr. (MemRead mr, Prim e) => mr -> ([e], [Word8]) Source #
Same as toListMem
, except when there is some slack towards the end of the memory
region that didn't fit into a list it will be returned as a list of bytes.
Examples
>>>
import Data.Word
>>>
:set -XDataKinds
>>>
a = fromListMem [0 .. 10 :: Word8] :: Bytes 'Pin
>>>
a
[0x00,0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0a]>>>
toListSlackMem a :: ([Word8], [Word8])
([0,1,2,3,4,5,6,7,8,9,10],[])>>>
toListSlackMem a :: ([Word16], [Word8])
([256,770,1284,1798,2312],[10])>>>
toListSlackMem a :: ([Word32], [Word8])
([50462976,117835012],[8,9,10])>>>
toListSlackMem a :: ([Word64], [Word8])
([506097522914230528],[8,9,10])
Since: 0.1.0
toByteListMem :: forall ma. MemAlloc ma => FrozenMem ma -> [Word8] Source #
Convert a memory region to a list of bytes. Equivalent to unpack
for ByteString
Example
>>>
toByteListMem (fromByteListMem [0..10] :: Bytes 'Pin)
[0,1,2,3,4,5,6,7,8,9,10]
Since: 0.1.0
foldrCountMem :: forall e b mr. (MemRead mr, Prim e) => Count e -> (e -> b -> b) -> b -> mr -> b Source #
Right fold that is useful for converting to a list while tapping into list fusion.
- Unsafe
- Supplying Count larger than memory holds will result in reading out of bounds and a potential segfault.
Since: 0.1.0
showsHexMem :: MemRead mr => mr -> [ShowS] Source #
A list of ShowS
which covert bytes to base16 encoded strings. Each element of the list
is a function that will convert one byte.
Example
>>>
:set -XDataKinds
>>>
import Data.Prim.Memory
>>>
concatMap ($ " ") $ showsHexMem (fromListMem [1 :: Int16 .. 15] :: Bytes 'Inc)
"01 00 02 00 03 00 04 00 05 00 06 00 07 00 08 00 09 00 0a 00 0b 00 0c 00 0d 00 0e 00 0f 00 "
Since: 0.1.0
From list
fromListMem :: forall e ma. (Prim e, MemAlloc ma) => [e] -> FrozenMem ma Source #
Just like fromListMemN
, except it ensures safety by using the length of the
list for allocation. Because it has to figure out the length of the list first it
will be just a little bit slower, but that much safer.
Examples
>>>
import Data.Prim.Memory
>>>
:set -XDataKinds
>>>
fromListMem "Hi" :: Bytes 'Inc
[0x48,0x00,0x00,0x00,0x69,0x00,0x00,0x00]
Since: 0.1.0
fromByteListMem :: forall ma. MemAlloc ma => [Word8] -> FrozenMem ma Source #
Same as fromListMem
but restricted to a list of Word8
. Load a list of bytes into
a newly allocated memory region. Equivalent to pack
for
ByteString
Examples
>>>
fromByteListMem [0..10] :: Bytes 'Pin
[0x00,0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0a]
Since: 0.1.0
:: (Prim e, MemAlloc ma) | |
=> Count e | memCount - Expected number of elements in the list, which exactly how much memory will be allocated. Preconditions: 0 <= memCount unCount memCount <= length list |
-> [e] | list - A list of elements to load into the newly allocated memory region. |
-> (Either [e] (Count e), FrozenMem ma) |
Similarly to fromListMem
load a list into a newly allocated memory region, but
unlike the aforementioned function it also accepts a hint of how many elements is
expected to be in the list. Because the number of expected an actual elements might
not match we return not only the frozen memory region, but also:
either a list with leftover elements from the input
list
, if it did not fully fit into the allocated region. An empty list would indicate that it did fit exactly.unCount memCount <= length list
- or an exact count of how many elements have been loaded when there was no enough elements in the list
In the latter case a zero value would indicate that the list did fit into the newly
allocated memory region exactly, which is perfectly fine. But a positive value would
mean that the tail of the memory region is still unset and might contain garbage
data. Make sure to overwrite the surplus memory yourself or use the safe version
fromListZeroMemN
that fills the surplus with zeros.
- Unsafe
- Whenever
memCount
precodition is violated, because on each call with the same input it can produce different output therefore it will break referential transparency.
Examples
>>>
:set -XTypeApplications
>>>
fromListMemN @Char @(MBytes 'Inc) 3 "Hello"
(Left "lo",[0x48,0x00,0x00,0x00,0x65,0x00,0x00,0x00,0x6c,0x00,0x00,0x00])>>>
fromListMemN @Char @(MBytes 'Inc) 2 "Hi"
(Left "",[0x48,0x00,0x00,0x00,0x69,0x00,0x00,0x00])>>>
fst $ fromListMemN @Char @(MBytes 'Inc) 5 "Hi"
Right (Count {unCount = 2})
Since: 0.2.0
:: (Prim e, MemAlloc ma) | |
=> Count e | memCount - Number of elements to load from the list. |
-> [e] | |
-> (Either [e] (Count e), FrozenMem ma) |
Just like fromListMemN
, except it ensures safety by filling tail with zeros,
whenever the list is not long enough.
Examples
>>>
import Data.Prim.Memory
>>>
:set -XTypeApplications
>>>
fromListZeroMemN @Char @(MBytes 'Inc) 3 "Hi"
(Right (Count {unCount = 2}),[0x48,0x00,0x00,0x00,0x69,0x00,0x00,0x00,0x00,0x00,0x00,0x00])
Since: 0.2.0
fromListZeroMemN_ :: forall e ma. (Prim e, MemAlloc ma) => Count e -> [e] -> FrozenMem ma Source #
Same as fromListZeroMemN
, but ignore the extra information about how the loading went.
Examples
>>>
import Data.Prim.Memory
>>>
fromListZeroMemN_ 3 "Hi" :: Bytes 'Inc
[0x48,0x00,0x00,0x00,0x69,0x00,0x00,0x00,0x00,0x00,0x00,0x00]
Since: 0.2.0
Mutable
data MBytes (p :: Pinned) s Source #
Mutable region of memory which was allocated either as pinned or unpinned.
Constructor is not exported for safety. Violating type level Pinned
kind is very
dangerous. Type safe constructor fromMutableByteArray#
and
unwrapper toMutableByteArray#
should be used instead. As a
backdoor, of course, the actual constructor is available in Data.Prim.Memory.Internal
module and specially unsafe function castPinnedMBytes
was crafted.
Instances
Type class that can be implemented for a mutable data type that provides direct read and write access to memory
readByteOffMem, writeByteOffMem, moveByteOffToMBytesMem, moveByteOffToPtrMem, copyByteOffMem, moveByteOffMem, setMem
Instances
class (MemRead (FrozenMem ma), MemWrite ma) => MemAlloc ma Source #
Generalized memory allocation and pure/mutable state conversion.
type FrozenMem ma = (fm :: Type) | fm -> ma Source #
Memory region in the immutable state. Types for frozen and thawed states of
memory region are in one-to-one correspondence, therefore ma - FrozeMem ma
will
always uniquely identify each other, which is an extremely useful property when it
comes to type inference.
Instances
A wrapper that adds a phantom state token. It can be used with types that either
doesn't have such state token or are designed to work in IO
and therefore restricted
to RW
. Using this wrapper is very much unsafe, so make sure you know what you are
doing.
MemState | |
|
Instances
Size
getCountMem :: forall e ma m s. (MemAlloc ma, MonadPrim s m, Prim e) => ma s -> m (Count e) Source #
getCountRemMem :: forall e ma m s. (MemAlloc ma, MonadPrim s m, Prim e) => ma s -> m (Count e, Count Word8) Source #
getByteCountMem :: (MemAlloc ma, MonadPrim s m) => ma s -> m (Count Word8) Source #
Extract from the mutable memory region information about how many bytes it can hold.
Since: 0.1.0
Read
:: (MemWrite mw, MonadPrim s m, Prim e) | |
=> mw s | memRead - Memory region to read an element from |
-> Off e | off - Offset in number of elements from the beginning of Preconditions: 0 <= off With offset applied it should still refer to the same memory region. For types that
also implement count <- getByteCountMem memRead unOff (toByteOff off) <= unCount (count - byteCountType @e) |
-> m e |
Read an element with an offset in number of elements, rather than bytes as it is
the case with readByteOffMem
.
- Unsafe
- Bounds are not checked. When precondition for
off
argument is violated the result is either unpredictable output or failure with a segfault.
Since: 0.1.0
:: (MemWrite mw, MonadPrim s m, Prim e) | |
=> mw s | memRead - Memory region to read an element from |
-> Off Word8 | off - Offset in number of elements from the beginning of Preconditions: 0 <= off With offset applied it should still refer to the same memory region. For types that
also implement count <- getByteCountMem memRead unOff (toByteOff off) <= unCount (count - byteCountType @e) |
-> m e |
Read an element with an offset in number of bytes.
- Unsafe
- Bounds are not checked. When precondition for
off
argument is violated the result is either unpredictable output or failure with a segfault.
Since: 0.1.0
Write
:: (MemWrite mw, MonadPrim s m, Prim e) | |
=> mw s | memWrite - Memory region to write an element into |
-> Off e | off - Offset in number of elements from the beginning of Preconditions: 0 <= off With offset applied it should still refer to the same memory region. For types that
also implement count <- getByteCountMem memWrite unOff (toByteOff off) <= unCount (count - byteCountType @e) |
-> e | elt - Element to write |
-> m () |
Write an element with an offset in number of elements, rather than bytes as it is
the case with writeByteOffMem
.
- Unsafe
- Bounds are not checked. When precondition for
off
argument is violated the outcome is either heap corruption or failure with a segfault.
Since: 0.1.0
:: (MemWrite mw, MonadPrim s m, Prim e) | |
=> mw s | memWrite - Memory region to write an element into |
-> Off Word8 | off - Offset in number of elements from the beginning of Preconditions: 0 <= off With offset applied it should still refer to the same memory region. For types that
also implement count <- getByteCountMem memWrite unOff (toByteOff off) <= unCount (count - byteCountType @e) |
-> e | |
-> m () |
Write an element with an offset in number of bytes.
- Unsafe
- Bounds are not checked. When precondition for
off
argument is violated the outcome is either heap corruption or failure with a segfault.
Since: 0.1.0
:: (MemWrite mw, MonadPrim s m, Prim e) | |
=> mw s | memTarget - Target memory into where to write the element |
-> Off e | memTargetOff - Offset into target memory in number of elements at which element setting should start. Preconditions: 0 <= memTargetOff With offset applied it should still refer to the same memory region. For types that
also implement targetByteCount <- getByteCountMem memTarget unOffBytes memTargetOff <= unCount (targetByteCount - byteCountType @e) |
-> Count e | memCount - Number of times the element Preconditions: 0 <= memCount Target memory region should have enough memory to perform a set operation of the
supplied element targetByteCount <- getByteCountMem memTarget unCountBytes memCount + unOff memTargetOff <= unCount (targetByteCount - byteCountType @e) |
-> e | elt - Element to write into memory cells. This function is strict with
respect to element, which means that the even |
-> m () |
Write the same value memCount
times into each cell of memTarget
starting at an
offset memTargetOff
.
- Unsafe
- Bounds are not checked. When precondition for
memTargetOff
argument is violated the outcome is either heap corruption or failure with a segfault.
Since: 0.1.0
modifyFetchOldMem :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off e -> (e -> e) -> m e Source #
modifyFetchOldMemM :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off e -> (e -> m e) -> m e Source #
modifyFetchNewMem :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off e -> (e -> e) -> m e Source #
modifyFetchNewMemM :: (MemWrite mw, MonadPrim s m, Prim e) => mw s -> Off e -> (e -> m e) -> m e Source #
Allocate
:: (MemAlloc ma, Prim e, MonadPrim s m) | |
=> Count e | memCount - Number of elements to allocate. Preconditions: 0 <= memCount Possibility of overflow: unCount memCount <= fromByteCount @e (Count maxBound) When converted to bytes the value should be less then available physical memory |
-> m (ma s) |
Allocate a mutable memory region for specified number of elements. Memory is not
reset and will likely hold some garbage data, therefore prefer to use allocZeroMem
,
unless it is guaranteed that all of allocated memory will be overwritten.
- Unsafe
- When precondition for
memCount
argument is violated the outcome is upredictable. One possible outcome is termination withHeapOverflow
async exception. In a pure setting, such as when executed withinrunST
, if memory is not fully overwritten it can result in violation of referential transparency, because content of newly allocated region is non-determinstic.
Since: 0.1.0
:: (MemAlloc ma, MonadPrim s m, Prim e) | |
=> Count e | memCount - Number of elements to allocate. Preconditions: 0 <= memCount Converted to bytes should be less then available physical memory |
-> m (ma s) |
Same as allocMem
, but also use setMem
to reset all of newly allocated memory to
zeros.
- Unsafe
- When precondition for
memCount
argument is violated the outcome is upredictable. One possible outcome is termination withHeapOverflow
async exception.
Example
>>>
:set -XTypeApplications
>>>
:set -XDataKinds
>>>
import Data.Prim.Memory
>>>
mb <- allocZeroMem @Int @(MBytes 'Inc) 10
>>>
b <- freezeMem mb
>>>
toListMem b :: [Int]
[0,0,0,0,0,0,0,0,0,0]
Since: 0.1.0
thawMem :: (MemAlloc ma, MonadPrim s m) => FrozenMem ma -> m (ma s) Source #
Convert the state of an immutable memory region to the mutable one. This is a no
copy operation, as such it is fast, but dangerous. See thawCopyMem
for a safe alternative.
- Unsafe
- It makes it possible to break referential transparency, because any subsequent destructive operation to the mutable region of memory will also be reflected in the frozen immutable type as well.
Since: 0.1.0
thawCloneMem :: forall mr ma m s. (MemRead mr, MemAlloc ma, MonadPrim s m) => mr -> m (ma s) Source #
thawCopyMem :: forall e mr ma m s. (Prim e, MemRead mr, MemAlloc ma, MonadPrim s m) => mr -> Off e -> Count e -> m (ma s) Source #
freezeMem :: (MemAlloc ma, MonadPrim s m) => ma s -> m (FrozenMem ma) Source #
Convert the state of a mutable memory region to the immutable one. This is a no
copy operation, as such it is fast, but dangerous. See freezeCopyMem
for a safe alternative.
- Unsafe
- It makes it possible to break referential transparency, because any subsequent destructive operation to the mutable region of memory will also be reflected in the frozen immutable type as well.
Since: 0.1.0
freezeCopyMem :: forall e ma m s. (Prim e, MemAlloc ma, MonadPrim s m) => ma s -> Off e -> Count e -> m (FrozenMem ma) Source #
:: (MemAlloc ma, MonadPrim s m, Prim e) | |
=> ma s | memSource - Source memory region to resize |
-> Count e | memCount - Number of elements for the reallocated memory region Preconditions: 0 <= memCount Should be less then available physical memory |
-> m (ma s) |
Either grow or shrink currently allocated mutable region of memory. For some
implementations it might be possible to change the size of the allocated region
in-place, i.e. without copy. However in all implementations there is a good chance
that the memory region has to be allocated anew, in which case all of the contents
up to the minimum of new and old sizes will get copied over. After the resize
operation is complete the supplied memSource
region must not be used
anymore. Moreover, no reference to the old one should be kept in order to allow
garbage collection of the original in case a new one had to be allocated.
- Unsafe
- Undefined behavior when
memSource
is used afterwards. The same unsafety notice fromallocMem
with regards tomemCount
is applcable here as well.
Since: 0.1.0
withScrubbedMem :: forall e ma m a. (MonadUnliftPrim RW m, Prim e, MemAlloc ma, PtrAccess RW (ma RW)) => Count e -> (ma RW -> m a) -> m a Source #
Ensure that memory is filled with zeros before and after it gets used. PtrAccess
is
not used directly, but istead is used to guarantee that the memory is pinned and its
contents do get moved around by the garbage collector.
Since: 0.2.0
Move
:: (MemWrite mw, MonadPrim s m, MemWrite mw', Prim e) | |
=> mw' s | memSource - Source memory from where to copy |
-> Off Word8 | memSourceOff - Offset in number of bytes into source memory Preconditions: 0 <= memSourceOff With offset applied it should still refer to the same memory region. For types that
also implement sourceByteCount <- getByteCountMem memSource unOffBytes memSourceOff <= unCount (sourceByteCount - byteCountType @e) |
-> mw s | memTarget - Target memory into where to copy |
-> Off Word8 | memTargetOff - Offset into target memory in number of bytes Preconditions: 0 <= memTargetOff With offset applied it should still refer to the same memory region. For types that
also implement targetByteCount <- getByteCountMem memTarget unOffBytes (toByteOff memTargetOff) <= unCount (targetByteCount - byteCountType @e) |
-> Count e | memCount - Number of elements of type Preconditions: 0 <= memCount Both source and target memory regions must have enough memory to perform a copy
of sourceByteCount <- getByteCountMem memSource unOff memSourceOff + unCountBytes memCount <= unCount (sourceByteCount - byteCountType @e) targetByteCount <- getByteCountMem memTarget unOff memTargetOff + unCountBytes memCount <= unCount (targetByteCount - byteCountType @e) |
-> m () |
Copy contiguous chunk of memory from a mutable memory region into the target mutable memory region. Source and target may refer to the same memory region.
- Unsafe
- When any precondition for one of the offsets
memSourceOff
,memTargetOff
or the element countmemCount
is violated a call to this function can result in: copy of data that doesn't belong tomemSourceRead
, heap corruption or failure with a segfault.
Since: 0.1.0
moveByteOffToMBytesMem Source #
:: (MemWrite mw, MonadPrim s m, Prim e) | |
=> mw s | memSource - Source memory from where to copy |
-> Off Word8 | memSourceOff - Offset in number of bytes into source memory Preconditions: 0 <= memSourceOff With offset applied it should still refer to the same memory region. For types that
also implement sourceByteCount <- getByteCountMem memSource unOff (toByteOff memSourceOff) <= unCount (sourceByteCount - byteCountType @e) |
-> MBytes p s | memTarget - Target memory into where to copy |
-> Off Word8 | memTargetOff - Offset in number of bytes into target memory where writing will start Preconditions: 0 <= memTargetOff With offset applied it should still refer to the same memory region. For types that
also implement targetByteCount <- getByteCountMem memTarget unOffBytes memTargetOff <= unCount (targetByteCount - byteCountType @e) |
-> Count e | memCount - Number of elements of type Preconditions: 0 <= memCount Both source and target memory regions must have enough memory to perform a copy
of sourceByteCount <- getByteCountMem memSource unOff memSourceOff + unCountBytes memCount <= unCount (sourceByteCount - byteCountType @e) targetByteCount <- getByteCountMem memTarget unOff memTargetOff + unCountBytes memCount <= unCount (targetByteCount - byteCountType @e) |
-> m () |
Copy contiguous chunk of memory from the source mutable memory into the target
mutable MBytes
. Source and target may refer to overlapping memory regions.
- Unsafe
- When any precondition for one of the offsets
memSourceOff
,memTargetOff
or the element countmemCount
is violated a call to this function can result in: copy of data that doesn't belong tomemSource
, heap corruption or failure with a segfault.
Since: 0.1.0
:: (MemWrite mw, MonadPrim s m, Prim e) | |
=> mw s | memSource - Source memory from where to copy |
-> Off Word8 | memSourceOff - Offset in number of bytes into source memory Preconditions: 0 <= memSourceOff With offset applied it should still refer to the same memory region. For types that
also implement sourceByteCount <- getByteCountMem memSource unOff (toByteOff memSourceOff) <= unCount (sourceByteCount - byteCountType @e) |
-> Ptr e | memTarget - Target memory into where to copy Precondition: Once the pointer is advanced by |
-> Off Word8 | memTargetOff - Offset in number of bytes into target memory where writing will start Preconditions: 0 <= memTargetOff Once the pointer is advanced by |
-> Count e | memCount - Number of elements of type Preconditions: 0 <= memCount Both source and target memory regions must have enough memory to perform a copy
of sourceByteCount <- getByteCountMem memSource unOff memSourceOff + unCountBytes memCount <= unCount (sourceByteCount - byteCountType @e) |
-> m () |
Copy contiguous chunk of memory from the source mutable memory into the target
Ptr
. Source and target may refer to overlapping memory regions.
- Unsafe
- When any precondition for one of the offsets
memSourceOff
ormemTargetOff
, a target pointermemTarget
or the element countmemCount
is violated a call to this function can result in: copy of data that doesn't belong tomemSource
, heap corruption or failure with a segfault.
Since: 0.1.0
Load list
:: (Prim e, MemAlloc ma, MonadPrim s m) | |
=> [e] | listSource - List with elements to load |
-> ma s | memTarget - Mutable region where to load elements from the list |
-> m ([e], Count e) | Leftover part of the |
Same as loadListMemN
, but tries to fit as many elements as possible into the mutable
memory region starting at the beginning. This operation is always safe.
Examples
>>>
import Data.Prim.Memory
>>>
ma <- allocMem (5 :: Count Char) :: IO (MBytes 'Inc RW)
>>>
loadListMem "HelloWorld" ma
("World",Count {unCount = 5})>>>
freezeMem ma
[0x48,0x00,0x00,0x00,0x65,0x00,0x00,0x00,0x6c,0x00,0x00,0x00,0x6c,0x00,0x00,0x00,0x6f,0x00,0x00,0x00]>>>
loadListMem (replicate 6 (0xff :: Word8)) ma
([],Count {unCount = 6})>>>
freezeMem ma
[0xff,0xff,0xff,0xff,0xff,0xff,0x00,0x00,0x6c,0x00,0x00,0x00,0x6c,0x00,0x00,0x00,0x6f,0x00,0x00,0x00]
Since: 0.2.0
:: (Prim e, MemAlloc ma, MonadPrim s m) | |
=> [e] | listSource - List with elements to load |
-> ma s | memTarget - Mutable region where to load elements from the list |
-> m () |
Same as loadListMem
, but ignores the result. Equivalence as property:
let c = fromInteger (abs i) :: Count Int in (createZeroMemST_ c (loadListMem_ (xs :: [Int])) :: Bytes 'Inc) == createZeroMemST_ c (void . loadListMem xs)
Since: 0.2.0
:: (MemWrite mw, MonadPrim s m, Prim e) | |
=> Count e | elemCount - Maximum number of elements to load from list into the memory region Preconditions: 0 <= memCount Target memory region must have enough memory to perform loading of targetCount <- getCountMem memTarget elemCount <= targetCount |
-> [e] | listSource - List with elements that should be loaded |
-> mw s | memTarget - Memory region where to load the elements into |
-> m ([e], Count e) | Leftover part of the |
Same as loadListOffMemN
, but start loading at 0
offset.
- Unsafe
- When any precondition for the element count
memCount
is violated then a call to this function can result in heap corruption or failure with a segfault.
Since: 0.2.0
:: (Prim e, MemWrite mw, MonadPrim s m) | |
=> Count e | elemCount - Maximum number of elements to load from list into the memory region Preconditions: 0 <= memCount Target memory region must have enough memory to perform loading of targetCount <- getCountMem memTarget elemCount <= targetCount |
-> [e] | listSource - List with elements that should be loaded |
-> mw s | memTarget - Memory region where to load the elements into |
-> m () |
Same as loadListMemN
, but ignores the result.
- Unsafe
- When any precondition for the element count
memCount
is violated then a call to this function can result in heap corruption or failure with a segfault.
Since: 0.2.0
With offset
:: (Prim e, MemAlloc ma, MonadPrim s m) | |
=> [e] | listSource - List with elements that should be loaded |
-> ma s | memTarget - Memory region where to load the elements into |
-> Off e | memTargetOff - Offset in number of elements into target memory where writing will start Preconditions: 0 <= memTargetOff Once the pointer is advanced by targetCount <- getCountMem memTarget unOff memTargetOff < unCount targetCount |
-> m ([e], Count e) | Leftover part of the |
Same as loadListOffMemN
, but infer the count from number of bytes that is available
in the target memory region.
- Unsafe
- When a precondition for the element count
memCount
is violated then a call to this function can result in heap corruption or failure with a segfault.
Since: 0.2.0
:: (MemWrite mw, MonadPrim s m, Prim e) | |
=> Count e | elemCount - Maximum number of elements to load from list into the memory region Preconditions: 0 <= memCount Target memory region must have enough memory to perform loading of targetCount <- getCountMem memTarget unOff memTargetOff + unCount elemCount < unCount targetCount |
-> [e] | listSource - List with elements that should be loaded |
-> mw s | memTarget - Memory region where to load the elements into |
-> Off e | memTargetOff - Offset in number of elements into target memory where writing will start Preconditions: 0 <= memTargetOff Once the pointer is advanced by targetCount <- getByteCountMem memTarget unOff memTargetOff < unCount targetCount |
-> m ([e], Count e) | Leftover part of the |
Same as loadListByteOffMemN
, but works with offset in number of elements instead of
bytes.
- Unsafe
- When preconditions for either the offset
memTargetOff
or the element countmemCount
is violated then a call to this function can result in heap corruption or failure with a segfault.
Since: 0.2.0
:: (MemAlloc ma, MonadPrim s m, Prim e) | |
=> [e] | listSource - List with elements that should be loaded |
-> ma s | memTarget - Memory region where to load the elements into |
-> Off Word8 | memTargetOff - Offset in number of bytes into target memory where writing will start Preconditions: 0 <= memTargetOff Once the pointer is advanced by targetByteCount <- getByteCountMem memTarget unOff memTargetOff <= unCount (targetByteCount - byteCountType @e) |
-> m ([e], Count e) | Leftover part of the |
Same as loadListByteOffMemN
, but infer the count from number of bytes that is
available in the target memory region.
- Unsafe
- When a precondition for the element count
memCount
is violated then a call to this function can result in heap corruption or failure with a segfault.
Examples
>>>
:set -XDataKinds
>>>
import Data.Prim.Memory
>>>
ma <- allocZeroMem (5 :: Count Char) :: IO (MBytes 'Inc RW)
>>>
freezeMem ma
[0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00]>>>
loadListByteOffMem "Hello World" ma 0
(" World",Count {unCount = 5})>>>
freezeMem ma
[0x48,0x00,0x00,0x00,0x65,0x00,0x00,0x00,0x6c,0x00,0x00,0x00,0x6c,0x00,0x00,0x00,0x6f,0x00,0x00,0x00]>>>
loadListByteOffMem ([0xff,0xff,0xff] :: [Word8]) ma 1
([],Count {unCount = 3})>>>
freezeMem ma
[0x48,0xff,0xff,0xff,0x65,0x00,0x00,0x00,0x6c,0x00,0x00,0x00,0x6c,0x00,0x00,0x00,0x6f,0x00,0x00,0x00]
Since: 0.2.0
:: (MemWrite mw, MonadPrim s m, Prim e) | |
=> Count e | elemCount - Maximum number of elements to load from list into the memory region Preconditions: 0 <= memCount Target memory region must have enough memory to perform loading of targetByteCount <- getByteCountMem memTarget unOff memTargetOff + unCountBytes elemCount <= unCount (targetByteCount - byteCountType @e) |
-> [e] | listSource - List with elements that should be loaded |
-> mw s | memTarget - Memory region where to load the elements into |
-> Off Word8 | memTargetOff - Offset in number of bytes into target memory where writing will start Preconditions: 0 <= memTargetOff Once the pointer is advanced by targetByteCount <- getByteCountMem memTarget unOff memTargetOff <= unCount (targetByteCount - byteCountType @e) |
-> m ([e], Count e) | Leftover part of the |
Load elements from the supplied list into a mutable memory region. Loading will
start at the supplied offset in number of bytes and will stop when either supplied
elemCount
number is reached or there are no more elements left in the list to
load. This action returns a list of elements that did not get loaded and the count of
how many elements did get loaded.
- Unsafe
- When any precondition for either the offset
memTargetOff
or the element countmemCount
is violated then a call to this function can result in heap corruption or failure with a segfault.
Examples
For example load the Hell
somewhere in the middle of MBytes
:
>>>
ma <- allocZeroMem (6 :: Count Char) :: IO (MBytes 'Inc RW)
>>>
loadListByteOffMemN 4 "Hello!" ma (toByteOff (1 :: Off Char))
("o!",Count {unCount = 4})>>>
freezeMem ma
[0x00,0x00,0x00,0x00,0x48,0x00,0x00,0x00,0x65,0x00,0x00,0x00,0x6c,0x00,0x00,0x00,0x6c,0x00,0x00,0x00,0x00,0x00,0x00,0x00]
Or something more usful like loading prefixes from nested lists:
>>>
import Control.Monad
>>>
foldM_ (\o xs -> (+ o) . countToByteOff . snd <$> loadListByteOffMemN 4 xs ma o) 2 [[x..] | x <- [1..5] :: [Word8]]
>>>
freezeMem ma
[0x00,0x00,0x01,0x02,0x03,0x04,0x02,0x03,0x04,0x05,0x03,0x04,0x05,0x06,0x04,0x05,0x06,0x07,0x05,0x06,0x07,0x08,0x00,0x00]
Since: 0.2.0