Safe Haskell	None
Language	Haskell2010

Haskus.Memory.View

Description

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

Synopsis

newtype View = View ViewIORef
data ViewSource
- = SourceBuffer (Buffer Immutable pin fin heap)
- | SourceWeakBuffer (Weak (Buffer Immutable pin fin heap))
- | SourceWeakView (Weak ViewIORef)
data ViewPattern
- = PatternFull
- | Pattern1D {
  - pattern1DOffset :: !Word
  - pattern1DSize :: !Word
  }
- | Pattern2D {
  - pattern2DOffset :: !Word
  - pattern2DWidth :: !Word
  - pattern2DHeight :: !Word
  - pattern2DStride :: !Word
  }
- | PatternOn ViewPattern ViewPattern
viewReadWord8 :: MonadIO m => View -> Word -> m Word8
newBufferView :: MonadIO m => Buffer Immutable pin fin heap -> ViewPattern -> m View
newBufferWeakView :: MonadIO m => Buffer Immutable pin fin heap -> ViewPattern -> m View
newViewWeakView :: MonadIO m => View -> ViewPattern -> m View
copyBufferWithPattern :: Buffer mut pin fin heap -> ViewPattern -> IO BufferM
viewToBuffer :: View -> IO BufferM
showViewState :: MonadIO m => View -> m String
patternSize :: ViewPattern -> Word -> Word
unsafePatternSize :: ViewPattern -> Word

Documentation

newtype View Source #

A view on a buffer

Constructors

View ViewIORef

data ViewSource Source #

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 Source #

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 Source #
Instance details Defined in Haskus.Memory.View Methods showsPrec :: Int -> ViewPattern -> ShowS # show :: ViewPattern -> String # showList :: [ViewPattern] -> ShowS #

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

Read a Word8 from a view

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

Create a view on a buffer

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

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 Source #

Create a weak view on a view

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

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

viewToBuffer :: View -> IO BufferM Source #

Convert a view into an actual buffer

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

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 Source #

Compute the effective size occupied by a pattern

unsafePatternSize :: ViewPattern -> Word Source #

Compute the effective size occupied by a pattern