haskus-binary-1.5: Haskus binary format manipulation

Safe HaskellNone
LanguageHaskell2010

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

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

Pattern2D

2D slice

Fields

PatternOn ViewPattern ViewPattern

Composed pattern

Instances
Show ViewPattern Source # 
Instance details

Defined in Haskus.Memory.View

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