Haskus.Memory.Buffer

A buffer in memory

Documentation

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

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

Serializable BufferI

Defined in Haskus.Format.Binary.Serialize

Associated Types

type SizeOf BufferI :: Size

type Endian BufferI :: Bool

Methods

sizeOf :: BufferI -> Word

put :: PutMonad m => Endianness -> BufferI -> m ()

get :: GetMonad m => Endianness -> Word -> m BufferI

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

Defined in Haskus.Format.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 :: Buffer mut pin0 gc0 heap0 -> BufferPutT (Buffer Mutable pin gc heap) m ()

preAllocateAtLeast :: Word -> BufferPutT (Buffer Mutable 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

type SizeOf BufferI

Defined in Haskus.Format.Binary.Serialize

type SizeOf BufferI = Dynamic

type Endian BufferI

Defined in Haskus.Format.Binary.Serialize

type Endian BufferI = False

newtype TypedBuffer (t :: k) mut pin fin heap

A buffer with an additional phantom type indicating its binary format

Constructors

TypedBuffer (Buffer mut pin fin heap)

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.Buffer

Methods

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

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

Show Pinning

Defined in Haskus.Memory.Buffer

Methods

showsPrec :: Int -> Pinning -> ShowS

show :: Pinning -> String

showList :: [Pinning] -> ShowS

data Finalization

Is the buffer automatically garbage collected?

Constructors

Collected

Automatically collected by the garbage-collector

Finalized

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

NotFinalized

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

Instances

Eq Finalization

Defined in Haskus.Memory.Buffer

Methods

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

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

Show Finalization

Defined in Haskus.Memory.Buffer

Methods

showsPrec :: Int -> Finalization -> ShowS

show :: Finalization -> String

showList :: [Finalization] -> ShowS

data Mutability

Is the buffer mutable or not?

Constructors

Mutable

Memory cells are mutable

Immutable

Memory cells are immutable

Instances

Eq Mutability

Defined in Haskus.Memory.Buffer

Methods

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

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

Show Mutability

Defined in Haskus.Memory.Buffer

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

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]

Reexport

module Control.Monad.Primitive