Haskus.Memory.View

A view (e.g. a slice) of a buffer

Suppose we have a big buffer B.

We can have buffer views on B, say vb1 and vb2.

B <----- vb1 ^------- vb2

These views don't duplicate B's contents and they keep B alive. If the views are much smaller than B, it may not be what we want: a lot of space is wasted and we would better duplicate B's data required by the views and free B.

To support this, we can use "weak buffer views", say wvb1 and wvb2.

B <~~~~~ wvb1 ^~~~~~~~ wvb2

If/when B is collected, new buffers are created from it for the views:

B1 <----- wvb1 B2 <----- wvb2

We can also create "weak view views", say wvv1 and wvv2:

B <~~~~~ wvb1 <~~~~~ wvv1 ^~~~~~~~~ wvv2

If/when B is collected before wvb1, the sharing is kept while the required contents of B is duplicated:

B' <---- wvb1 <~~~~~ wvv1 ^~~~~~~~~ wvv2

When wvb1 is collected, we can be in one of the following state depending if B has been collected already or not:

B <~~~~~~~~~~~~~~~~~ wvv1 ^~~~~~~~~~~~~~~~~~~~ wvv2

B' <~~~~~ wvv1 ^~~~~~~~~ wvv2

Documentation

newtype View

A view on a buffer

Constructors

View ViewIORef

data ViewSource

The source of a view

Weak views are used so that the underlying buffer can be freed by the GC. When it happens and if the view is still alive the contents of the buffer used by the view is copied into a fresh (usually smaller) buffer.

Weak views can also be used as sources: in this case, when the source view is GCed, the current view is updated to point to the source of the source.

Constructors

SourceBuffer (Buffer Immutable pin fin heap)

The source is a buffer. The view keeps the buffer alive

SourceWeakBuffer (Weak (Buffer Immutable pin fin heap))

The source is a weak buffer. If the buffer is collected, its contents is copied in to a new buffer and the view is updated to use it.

SourceWeakView (Weak ViewIORef)

The source is a weak view. If the source view is collected, the current view is updated to use whatever the source view uses as a source (another view or a buffer). This mechanism makes buffer contents cascade into smaller views while preserving some sharing.

data ViewPattern

A view pattern

Constructors

PatternFull

The whole buffer

Pattern1D

1D slice

Fields

• pattern1DOffset :: !Word

  Offset of the first cell

• pattern1DSize :: !Word

  Number of cells

Pattern2D

2D slice

Fields

• pattern2DOffset :: !Word

  Offset of the first line

• pattern2DWidth :: !Word

  Width (line size)

• pattern2DHeight :: !Word

  Height (number of lines)

• pattern2DStride :: !Word

  Stride (space between two lines)

PatternOn ViewPattern ViewPattern

Composed pattern

Instances

Show ViewPattern

Defined in Haskus.Memory.View

Methods

showsPrec :: Int -> ViewPattern -> ShowS

show :: ViewPattern -> String

showList :: [ViewPattern] -> ShowS

viewReadWord8 :: MonadIO m => View -> Word -> m Word8

Read a Word8 from a view

newBufferView :: MonadIO m => Buffer Immutable pin fin heap -> ViewPattern -> m View

Create a view on a buffer

newBufferWeakView :: MonadIO m => Buffer Immutable pin fin heap -> ViewPattern -> m View

Create a weak view on a buffer

The buffer is weakly referenced and can be GCed. When it happens, its contents is stored into a new buffer.

You should only use this for views that are much smaller than the original buffer so that the copying cost is balanced by the memory occupation difference.

newViewWeakView :: MonadIO m => View -> ViewPattern -> m View

Create a weak view on a view

copyBufferWithPattern :: Buffer mut pin fin heap -> ViewPattern -> IO BufferM

Allocate a new buffer initialized with the contents of the source buffer according to the given pattern

viewToBuffer :: View -> IO BufferM

Convert a view into an actual buffer

showViewState :: MonadIO m => View -> m String

Display the state of a View

>>> :set -XOverloadedLists
>>> import System.Mem
>>> v <- newBufferWeakView ([10,11,12,13,14,15,16,17] :: BufferI) (Pattern1D 2 4)
>>> v2 <- newViewWeakView v (Pattern1D 1 1)

putStr =<< showViewState v2

View source: weak view Source size: 4 View pattern: Pattern1D {pattern1DOffset = 1, pattern1DSize = 1} Wasted space: 75% Source: View source: weak buffer Source size: 8 View pattern: Pattern1D {pattern1DOffset = 2, pattern1DSize = 4} Wasted space: 50%

performGC
putStr =<< showViewState v2

View source: weak view Source size: 4 View pattern: Pattern1D {pattern1DOffset = 1, pattern1DSize = 1} Wasted space: 75% Source: View source: buffer Source size: 4 View pattern: PatternFull Wasted space: 0%

patternSize :: ViewPattern -> Word -> Word

Compute the effective size occupied by a pattern

unsafePatternSize :: ViewPattern -> Word

Compute the effective size occupied by a pattern