Haskus.Memory.Buffer

A buffer in memory

Documentation

data Buffer (mut :: Mutability) (pin :: Pinning) (fin :: Finalization) (heap :: Heap) where

A memory buffer

Constructors

Buffer :: !ByteArray# -> BufferI

BufferP :: !ByteArray# -> BufferP

BufferM :: !(MutableByteArray# RealWorld) -> BufferM

BufferMP :: !(MutableByteArray# RealWorld) -> BufferMP

BufferME :: Addr# -> !Word -> BufferME

BufferE :: Addr# -> !Word -> BufferE

BufferF :: !ByteArray# -> !Finalizers -> BufferF

BufferPF :: !ByteArray# -> !Finalizers -> BufferPF

BufferMF :: !(MutableByteArray# RealWorld) -> !Finalizers -> BufferMF

BufferMPF :: !(MutableByteArray# RealWorld) -> !Finalizers -> BufferMPF

BufferMEF :: Addr# -> !Word -> !Finalizers -> BufferMEF

BufferEF :: Addr# -> !Word -> !Finalizers -> BufferEF

Instances

IsList BufferI

Support for OverloadedLists

>>> :set -XOverloadedLists
>>> let b = [25,26,27,28] :: BufferI

Defined in Haskus.Memory.Buffer

Associated Types

type Item BufferI :: Type

Methods

fromList :: [Item BufferI] -> BufferI

fromListN :: Int -> [Item BufferI] -> BufferI

toList :: BufferI -> [Item BufferI]

BufferToList BufferPF

Defined in Haskus.Memory.Buffer

Methods

bufferToList :: BufferPF -> [Word8]

BufferToList BufferF

Defined in Haskus.Memory.Buffer

Methods

bufferToList :: BufferF -> [Word8]

BufferToList BufferP

Defined in Haskus.Memory.Buffer

Methods

bufferToList :: BufferP -> [Word8]

BufferToList BufferI

Defined in Haskus.Memory.Buffer

Methods

bufferToList :: BufferI -> [Word8]

BufferSize BufferEF

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferEF -> Word

BufferSize BufferMEF

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferMEF -> Word

BufferSize BufferPF

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferPF -> Word

BufferSize BufferF

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferF -> Word

BufferSize BufferE

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferE -> Word

BufferSize BufferME

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferME -> Word

BufferSize BufferP

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferP -> Word

BufferSize BufferI

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferI -> Word

MonadIO m => PutMonad (BufferPutT (Buffer Mutable pin gc heap) m)

Defined in Haskus.Binary.Serialize.Buffer

Methods

putWord8 :: Word8 -> BufferPutT (Buffer Mutable pin gc heap) m ()

putWord16 :: Word16 -> BufferPutT (Buffer Mutable pin gc heap) m ()

putWord32 :: Word32 -> BufferPutT (Buffer Mutable pin gc heap) m ()

putWord64 :: Word64 -> BufferPutT (Buffer Mutable pin gc heap) m ()

putWord8s :: [Word8] -> BufferPutT (Buffer Mutable pin gc heap) m ()

putWord16s :: [Word16] -> BufferPutT (Buffer Mutable pin gc heap) m ()

putWord32s :: [Word32] -> BufferPutT (Buffer Mutable pin gc heap) m ()

putWord64s :: [Word64] -> BufferPutT (Buffer Mutable pin gc heap) m ()

putBuffer :: BufferSize (Buffer Immutable pin0 gc0 heap0) => Buffer Immutable pin0 gc0 heap0 -> BufferPutT (Buffer Mutable pin gc heap) m ()

preAllocateAtLeast :: Word -> BufferPutT (Buffer Mutable pin gc heap) m ()

MonadIO m => GetMonad (BufferGetT (Buffer mut pin gc heap) m)

Defined in Haskus.Binary.Serialize.Buffer

Methods

getWord8 :: BufferGetT (Buffer mut pin gc heap) m Word8

getWord16 :: BufferGetT (Buffer mut pin gc heap) m Word16

getWord32 :: BufferGetT (Buffer mut pin gc heap) m Word32

getWord64 :: BufferGetT (Buffer mut pin gc heap) m Word64

getWord8s :: Word -> BufferGetT (Buffer mut pin gc heap) m [Word8]

getWord16s :: Word -> BufferGetT (Buffer mut pin gc heap) m [Word16]

getWord32s :: Word -> BufferGetT (Buffer mut pin gc heap) m [Word32]

getWord64s :: Word -> BufferGetT (Buffer mut pin gc heap) m [Word64]

getBuffer :: Word -> BufferGetT (Buffer mut pin gc heap) m BufferI

getBufferInto :: Word -> Buffer Mutable pin0 gc0 heap0 -> Maybe Word -> BufferGetT (Buffer mut pin gc heap) m ()

getSkipBytes :: Word -> BufferGetT (Buffer mut pin gc heap) m ()

Thawable (Buffer Immutable pin NotFinalized heap) (Buffer Mutable pin NotFinalized heap)

Defined in Haskus.Memory.Buffer

Methods

unsafeBufferThaw :: MonadIO m => Buffer Immutable pin NotFinalized heap -> m (Buffer Mutable pin NotFinalized heap)

Thawable (Buffer Immutable pin Collected heap) (Buffer Mutable pin Collected heap)

Defined in Haskus.Memory.Buffer

Methods

unsafeBufferThaw :: MonadIO m => Buffer Immutable pin Collected heap -> m (Buffer Mutable pin Collected heap)

Freezable (Buffer Mutable pin fin External) (Buffer Immutable pin fin External)

Defined in Haskus.Memory.Buffer

Methods

unsafeBufferFreeze :: MonadIO m => Buffer Mutable pin fin External -> m (Buffer Immutable pin fin External)

Freezable (Buffer Mutable pin Collected heap) (Buffer Immutable pin Collected heap)

Defined in Haskus.Memory.Buffer

Methods

unsafeBufferFreeze :: MonadIO m => Buffer Mutable pin Collected heap -> m (Buffer Immutable pin Collected heap)

type Item BufferI

Defined in Haskus.Memory.Buffer

type Item BufferI = Word8

newtype AnyBuffer

Wrapper containing any kind of buffer

Constructors

AnyBuffer (forall mut pin fin heap. Buffer mut pin fin heap)

Buffer taxonomy

data Pinning

Is the buffer pinned into memory?

Constructors

Pinned

The buffer has a fixed associated memory address

NotPinned

The buffer contents can be freely moved to another address

Instances

Eq Pinning

Defined in Haskus.Memory.Property

Methods

(==) :: Pinning -> Pinning -> Bool

(/=) :: Pinning -> Pinning -> Bool

Show Pinning

Defined in Haskus.Memory.Property

Methods

showsPrec :: Int -> Pinning -> ShowS

show :: Pinning -> String

showList :: [Pinning] -> ShowS

data Finalization

Is the memory automatically garbage collected?

Constructors

Collected

Automatically collected by the garbage-collector

Finalized

Finalizers are run just before the garbage collector collects the referencing entity (buffer, pointer...). The memory used by the entity may be collected too (Internal heap), explicitly freed by a finalizer or not freed at all.

NotFinalized

The memory is not automatically freed and we can't attach finalizers to the buffer.

Instances

Eq Finalization

Defined in Haskus.Memory.Property

Methods

(==) :: Finalization -> Finalization -> Bool

(/=) :: Finalization -> Finalization -> Bool

Show Finalization

Defined in Haskus.Memory.Property

Methods

showsPrec :: Int -> Finalization -> ShowS

show :: Finalization -> String

showList :: [Finalization] -> ShowS

data Mutability

Is the memory mutable or not?

Constructors

Mutable

Memory cells are mutable

Immutable

Memory cells are immutable

Instances

Eq Mutability

Defined in Haskus.Memory.Property

Methods

(==) :: Mutability -> Mutability -> Bool

(/=) :: Mutability -> Mutability -> Bool

Show Mutability

Defined in Haskus.Memory.Property

Methods

showsPrec :: Int -> Mutability -> ShowS

show :: Mutability -> String

showList :: [Mutability] -> ShowS

data Heap

Allocation heap

Constructors

Internal

GHC heap

External

External heap

type BufferI = Buffer Immutable NotPinned Collected Internal

type BufferP = Buffer Immutable Pinned Collected Internal

type BufferM = Buffer Mutable NotPinned Collected Internal

type BufferMP = Buffer Mutable Pinned Collected Internal

type BufferME = Buffer Mutable Pinned NotFinalized External

type BufferE = Buffer Immutable Pinned NotFinalized External

type BufferF = Buffer Immutable NotPinned Finalized Internal

type BufferPF = Buffer Immutable Pinned Finalized Internal

type BufferMF = Buffer Mutable NotPinned Finalized Internal

type BufferMPF = Buffer Mutable Pinned Finalized Internal

type BufferMEF = Buffer Mutable Pinned Finalized External

type BufferEF = Buffer Immutable Pinned Finalized External

GHC allocator

newBuffer :: MonadIO m => Word -> m BufferM

Allocate a buffer (mutable, unpinned)

>>> b <- newBuffer 1024

newPinnedBuffer :: MonadIO m => Word -> m BufferMP

Allocate a buffer (mutable, pinned)

newAlignedPinnedBuffer :: MonadIO m => Word -> Word -> m BufferMP

Allocate an aligned buffer (mutable, pinned)

Buffer size

bufferSizeIO :: MonadIO m => Buffer mut pin fin heap -> m Word

Get buffer size

class BufferSize a where

Methods

bufferSize :: a -> Word

Get buffer size

Instances

BufferSize BufferEF

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferEF -> Word

BufferSize BufferMEF

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferMEF -> Word

BufferSize BufferPF

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferPF -> Word

BufferSize BufferF

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferF -> Word

BufferSize BufferE

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferE -> Word

BufferSize BufferME

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferME -> Word

BufferSize BufferP

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferP -> Word

BufferSize BufferI

Defined in Haskus.Memory.Buffer

Methods

bufferSize :: BufferI -> Word

Buffer freeze/thaw

class Freezable a b | a -> b where

Buffer that can be frozen (converted from mutable to immutable)

Methods

unsafeBufferFreeze :: MonadIO m => a -> m b

Convert a mutable buffer to an immutable one without copying. The buffer should not be modified after the conversion.

Instances

Freezable (Buffer Mutable pin fin External) (Buffer Immutable pin fin External)

Defined in Haskus.Memory.Buffer

Methods

unsafeBufferFreeze :: MonadIO m => Buffer Mutable pin fin External -> m (Buffer Immutable pin fin External)

Freezable (Buffer Mutable pin Collected heap) (Buffer Immutable pin Collected heap)

Defined in Haskus.Memory.Buffer

Methods

unsafeBufferFreeze :: MonadIO m => Buffer Mutable pin Collected heap -> m (Buffer Immutable pin Collected heap)

class Thawable a b | a -> b where

Buffer that can be thawed (converted from immutable to mutable)

Methods

unsafeBufferThaw :: MonadIO m => a -> m b

Convert an immutable buffer to a mutable one without copying. The original buffer should not be used after the conversion.

Instances

Thawable (Buffer Immutable pin NotFinalized heap) (Buffer Mutable pin NotFinalized heap)

Defined in Haskus.Memory.Buffer

Methods

unsafeBufferThaw :: MonadIO m => Buffer Immutable pin NotFinalized heap -> m (Buffer Mutable pin NotFinalized heap)

Thawable (Buffer Immutable pin Collected heap) (Buffer Mutable pin Collected heap)

Defined in Haskus.Memory.Buffer

Methods

unsafeBufferThaw :: MonadIO m => Buffer Immutable pin Collected heap -> m (Buffer Mutable pin Collected heap)

Buffer address

bufferIsDynamicallyPinned :: Buffer mut pin fin heap -> Bool

Some buffers managed by GHC can be pinned as an optimization. This function reports this.

bufferDynamicallyPinned :: Buffer mut pin fin heap -> Either (Buffer mut NotPinned fin heap) (Buffer mut Pinned fin heap)

Transform type-level NotPinned buffers into type-level Pinned if the buffer is dynamically pinned (see bufferIsDynamicallyPinned).

withBufferAddr# :: MonadIO m => Buffer Mutable Pinned fin heap -> (Addr# -> m a) -> m a

Do something with a buffer address

withBufferPtr :: MonadIO m => Buffer Mutable Pinned fin heap -> (Ptr b -> m a) -> m a

Do something with a buffer pointer

unsafeWithBufferAddr# :: MonadIO m => Buffer mut Pinned fin heap -> (Addr# -> m a) -> m a

Do something with a buffer address

Note: don't write into immutable buffer as it would break referential consistency

unsafeWithBufferPtr :: MonadIO m => Buffer mut Pinned fin heap -> (Ptr b -> m a) -> m a

Do something with a buffer pointer

Note: don't write into immutable buffer as it would break referential consistency

Buffer read

bufferReadWord8IO :: MonadIO m => Buffer mut pin fin heap -> Word -> m Word8

Read a Word8, offset in bytes

We don't check that the offset is valid

>>> let b = [25,26,27,28] :: BufferI
>>> bufferReadWord8IO b 2
27

bufferReadWord8 :: Buffer Immutable pin fin heap -> Word -> Word8

Read a Word8 in an immutable buffer, offset in bytes

We don't check that the offset is valid

>>> let b = [25,26,27,28] :: BufferI
>>> putStrLn $ "Word8 at offset 2 is " ++ show (bufferReadWord8 b 2)
Word8 at offset 2 is 27

bufferReadWord16IO :: MonadIO m => Buffer mut pin fin heap -> Word -> m Word16

Read a Word16, offset in bytes

We don't check that the offset is valid

>>> let b = [0x12,0x34,0x56,0x78] :: BufferI
>>> x <- bufferReadWord16IO b 0
>>> (x == 0x1234) || (x == 0x3412)
True

bufferReadWord16 :: Buffer Immutable pin fin heap -> Word -> Word16

Read a Word16 in an immutable buffer, offset in bytes

We don't check that the offset is valid

bufferReadWord32IO :: MonadIO m => Buffer mut pin fin heap -> Word -> m Word32

Read a Word32, offset in bytes

We don't check that the offset is valid

>>> let b = [0x12,0x34,0x56,0x78] :: BufferI
>>> x <- bufferReadWord32IO b 0
>>> (x == 0x12345678) || (x == 0x78563412)
True

bufferReadWord32 :: Buffer Immutable pin fin heap -> Word -> Word32

Read a Word32 in an immutable buffer, offset in bytes

We don't check that the offset is valid

bufferReadWord64IO :: MonadIO m => Buffer mut pin fin heap -> Word -> m Word64

Read a Word64, offset in bytes

We don't check that the offset is valid

>>> let b = [0x12,0x34,0x56,0x78,0x9A,0xBC,0xDE,0xF0] :: BufferI
>>> x <- bufferReadWord64IO b 0
>>> (x == 0x123456789ABCDEF0) || (x == 0xF0DEBC9A78563412)
True

bufferReadWord64 :: Buffer Immutable pin fin heap -> Word -> Word64

Read a Word64 in an immutable buffer, offset in bytes

We don't check that the offset is valid

Buffer write and copy

bufferWriteWord8IO :: MonadIO m => Buffer Mutable pin fin heap -> Word -> Word8 -> m ()

Write a Word8, offset in bytes

We don't check that the offset is valid

>>> b <- newBuffer 10
>>> bufferWriteWord8IO b 1 123
>>> bufferReadWord8IO b 1
123

bufferWriteWord16IO :: MonadIO m => Buffer Mutable pin fin heap -> Word -> Word16 -> m ()

Write a Word16, offset in bytes

We don't check that the offset is valid

>>> b <- newBuffer 10
>>> let v = 1234 :: Word16
>>> bufferWriteWord16IO b 1 v
>>> bufferReadWord16IO b 1
1234

>>> (x :: Word16) <- fromIntegral <$> bufferReadWord8IO b 1
>>> (y :: Word16) <- fromIntegral <$> bufferReadWord8IO b 2
>>> (((x `shiftL` 8) .|. y) == v)   ||   (((y `shiftL` 8) .|. x) == v)
True

bufferWriteWord32IO :: MonadIO m => Buffer Mutable pin fin heap -> Word -> Word32 -> m ()

Write a Word32, offset in bytes

We don't check that the offset is valid

>>> b <- newBuffer 10
>>> let v = 1234 :: Word32
>>> bufferWriteWord32IO b 1 v
>>> bufferReadWord32IO b 1
1234

bufferWriteWord64IO :: MonadIO m => Buffer Mutable pin fin heap -> Word -> Word64 -> m ()

Write a Word64, offset in bytes

We don't check that the offset is valid

>>> b <- newBuffer 10
>>> let v = 1234 :: Word64
>>> bufferWriteWord64IO b 1 v
>>> bufferReadWord64IO b 1
1234

copyBuffer

Arguments

:: MonadIO m

=> Buffer mut pin0 fin0 heap0

Source buffer

-> Word

Offset in source buffer

-> Buffer Mutable pin1 fin1 heap1

Target buffer

-> Word

Offset in target buffer

-> Word

Number of Word8 to copy

-> m ()

Copy a buffer into another from/to the given offsets

We don't check buffer limits.

>>> let b = [0,1,2,3,4,5,6,7,8] :: BufferI
>>> b2 <- newBuffer 8
>>> copyBuffer b 4 b2 0 4
>>> copyBuffer b 0 b2 4 4
>>> forM [0..7] (bufferReadWord8IO b2)
[4,5,6,7,0,1,2,3]

Finalizers

data Finalizers

addFinalizer :: MonadIO m => Buffer mut pin Finalized heap -> IO () -> m ()

Add a finalizer.

The latest added finalizers are executed first. Finalizers are not guaranteed to run (e.g. if the program exits before the buffer is collected).

makeFinalizable :: MonadIO m => Buffer mut pin f heap -> m (Buffer mut pin Finalized heap)

Make a buffer finalizable

The new buffer liveness is used to trigger finalizers.

touchBuffer :: MonadIO m => Buffer mut pin fin heap -> m ()

Touch a buffer

touch :: MonadIO m => a -> m ()

Touch a data

Conversions

bufferToListIO :: MonadIO m => Buffer mut pin fin heap -> m [Word8]

Get contents as a list of bytes

class BufferToList a where

Methods

bufferToList :: a -> [Word8]

Get contents as a list of bytes

Instances

BufferToList BufferPF

Defined in Haskus.Memory.Buffer

Methods

bufferToList :: BufferPF -> [Word8]

BufferToList BufferF

Defined in Haskus.Memory.Buffer

Methods

bufferToList :: BufferF -> [Word8]

BufferToList BufferP

Defined in Haskus.Memory.Buffer

Methods

bufferToList :: BufferP -> [Word8]

BufferToList BufferI

Defined in Haskus.Memory.Buffer

Methods

bufferToList :: BufferI -> [Word8]