HMath.API.Buffer

Module index · Numerical conventions

Description

Checked containers and copying conversion boundaries. Boxed containers can retain lazy elements; strictBoxed forces each element to WHNF, not deep NF. Unboxed storage specializes to Double. ST regions cannot escape runSTBuffer; IO storage has one ForeignPtr owner shared by aliases and is garbage collected. IO operations synchronize on the buffer lock. Pointer callbacks borrow storage only for their dynamic extent and must not retain the pointer or reenter the same buffer's locking operations. Freeze and thaw always copy.

On this page

API	Purpose
Boxed	Immutable boxed array preserving element laziness unless built with strictBoxed; conversions preserve logical order.
lazyBoxed	Finite lists only.
strictBoxed	Construct a boxed container from a finite list, forcing every element to weak head normal form (not deep normal form).
boxedValues	Return boxed elements in zero-based array order as a list.
boxedLength	Return the number of elements in a boxed container; empty storage has length zero.
mapStrict	Given element transformation then boxed input, return a boxed result with every mapped element forced to WHNF.
UnboxedDouble	Immutable unboxed Double storage.
unboxedDouble	Copy a finite Double list into an immutable unboxed array in list order.
unboxedValues	Copy/expand unboxed Doubles into a list in array order, preserving length.
STBuffer	Mutable boxed storage confined by the ST state parameter.
runSTBuffer	The rank-2 state parameter prevents a mutable region from escaping.
thawSTBuffer	Copy immutable boxed values into new mutable storage in the current ST region.
freezeSTBuffer	Copy current mutable ST values into an immutable boxed container; later writes do not modify the frozen result.
readSTBuffer	Given ST buffer then zero-based index, read the element.
writeSTBuffer	Given ST buffer, zero-based index, then value, update one element and return Right ().
IOBuffer	Pinned garbage-collected Storable buffer with synchronized IO access.
newIOBuffer	Allocation overflow is checked before allocation.
thawIOBuffer	Copy boxed Storable values into new pinned IO storage.
freezeIOBuffer	Lock and copy pinned IO values to a strict immutable boxed container.
ioBufferLength	Return the immutable element count of a pinned IO buffer.
readIOBuffer	Given IO buffer then zero-based index, read under the buffer lock.
writeIOBuffer	Given IO buffer, zero-based index, then value, write under its lock and return Right ().
withIOBuffer	Given IO buffer then callback, hold its lock and lend a Ptr plus element count for the callback duration.
unboxedToBoxed	Convert unboxed Double storage to a new strict boxed container, preserving order and values.
boxedToUnboxed	Convert boxed Double values to a new unboxed array, forcing values during copying.

Documentation

Boxed

data Boxed a Source #

Immutable boxed array preserving element laziness unless built with strictBoxed; conversions preserve logical order.

Instances

Instances details

Functor Boxed Source #
Instance details Defined in HMath.API.Buffer Methods fmap :: (a -> b) -> Boxed a -> Boxed b # (<$) :: a -> Boxed b -> Boxed a #
Foldable Boxed Source #
Instance details Defined in HMath.API.Buffer Methods fold :: Monoid m => Boxed m -> m # foldMap :: Monoid m => (a -> m) -> Boxed a -> m # foldMap' :: Monoid m => (a -> m) -> Boxed a -> m # foldr :: (a -> b -> b) -> b -> Boxed a -> b # foldr' :: (a -> b -> b) -> b -> Boxed a -> b # foldl :: (b -> a -> b) -> b -> Boxed a -> b # foldl' :: (b -> a -> b) -> b -> Boxed a -> b # foldr1 :: (a -> a -> a) -> Boxed a -> a # foldl1 :: (a -> a -> a) -> Boxed a -> a # toList :: Boxed a -> [a] # null :: Boxed a -> Bool # length :: Boxed a -> Int # elem :: Eq a => a -> Boxed a -> Bool # maximum :: Ord a => Boxed a -> a # minimum :: Ord a => Boxed a -> a # sum :: Num a => Boxed a -> a # product :: Num a => Boxed a -> a #
Traversable Boxed Source #
Instance details Defined in HMath.API.Buffer Methods traverse :: Applicative f => (a -> f b) -> Boxed a -> f (Boxed b) # sequenceA :: Applicative f => Boxed (f a) -> f (Boxed a) # mapM :: Monad m => (a -> m b) -> Boxed a -> m (Boxed b) # sequence :: Monad m => Boxed (m a) -> m (Boxed a) #
Show a => Show (Boxed a) Source #
Instance details Defined in HMath.API.Buffer Methods showsPrec :: Int -> Boxed a -> ShowS # show :: Boxed a -> String # showList :: [Boxed a] -> ShowS #
Eq a => Eq (Boxed a) Source #
Instance details Defined in HMath.API.Buffer Methods (==) :: Boxed a -> Boxed a -> Bool # (/=) :: Boxed a -> Boxed a -> Bool #

lazyBoxed

lazyBoxed :: [a] -> Boxed a Source #

Finite lists only. The list spine is consumed; elements remain lazy.

strictBoxed

strictBoxed :: [a] -> Boxed a Source #

Construct a boxed container from a finite list, forcing every element to weak head normal form (not deep normal form). Preserve order; element evaluation exceptions propagate.

boxedValues

boxedValues :: Boxed a -> [a] Source #

Return boxed elements in zero-based array order as a list. Elements retain the laziness/strictness chosen at construction.

boxedLength

boxedLength :: Boxed a -> Int Source #

Return the number of elements in a boxed container; empty storage has length zero.

mapStrict

mapStrict :: (a -> b) -> Boxed a -> Boxed b Source #

Given element transformation then boxed input, return a boxed result with every mapped element forced to WHNF. Preserve length/order; evaluation exceptions propagate.

UnboxedDouble

data UnboxedDouble Source #

Immutable unboxed Double storage. Construct with unboxedDouble; boxed conversions copy.

Instances

Instances details

Show UnboxedDouble Source #
Instance details Defined in HMath.API.Buffer Methods showsPrec :: Int -> UnboxedDouble -> ShowS # show :: UnboxedDouble -> String # showList :: [UnboxedDouble] -> ShowS #
Eq UnboxedDouble Source #
Instance details Defined in HMath.API.Buffer Methods (==) :: UnboxedDouble -> UnboxedDouble -> Bool # (/=) :: UnboxedDouble -> UnboxedDouble -> Bool #

unboxedDouble

unboxedDouble :: [Double] -> UnboxedDouble Source #

Copy a finite Double list into an immutable unboxed array in list order. Values are evaluated by unboxing; no finiteness validation is added.

unboxedValues

unboxedValues :: UnboxedDouble -> [Double] Source #

Copy/expand unboxed Doubles into a list in array order, preserving length.

STBuffer

data STBuffer s a Source #

Mutable boxed storage confined by the ST state parameter. Freeze/thaw copy; use runSTBuffer to prevent region escape.

runSTBuffer

runSTBuffer :: Boxed a -> (forall s. STBuffer s a -> ST s b) -> b Source #

The rank-2 state parameter prevents a mutable region from escaping.

thawSTBuffer

thawSTBuffer :: Boxed a -> ST s (STBuffer s a) Source #

Copy immutable boxed values into new mutable storage in the current ST region. The input remains unchanged; storage cannot escape the region.

freezeSTBuffer

freezeSTBuffer :: STBuffer s a -> ST s (Boxed a) Source #

Copy current mutable ST values into an immutable boxed container; later writes do not modify the frozen result.

readSTBuffer

readSTBuffer :: STBuffer s a -> Int -> ST s (Either MathError a) Source #

Given ST buffer then zero-based index, read the element. Negative/out-of-range indices return Left InvalidArgument within ST, rather than indexing the array.

writeSTBuffer

writeSTBuffer :: STBuffer s a -> Int -> a -> ST s (Either MathError ()) Source #

Given ST buffer, zero-based index, then value, update one element and return Right (). Invalid index returns Left InvalidArgument without writing.

IOBuffer

data IOBuffer a Source #

Pinned garbage-collected Storable buffer with synchronized IO access. Pointer callbacks borrow storage only for their dynamic lifetime.

newIOBuffer

newIOBuffer :: Storable a => Int -> a -> IO (Either MathError (IOBuffer a)) Source #

Allocation overflow is checked before allocation. Allocation/OS exceptions remain IO exceptions; MathError describes input and numeric contract failures.

thawIOBuffer

thawIOBuffer :: Storable a => Boxed a -> IO (Either MathError (IOBuffer a)) Source #

Copy boxed Storable values into new pinned IO storage. Return Left InvalidArgument for byte-size overflow; allocationOSevaluation failures remain IO exceptions.

freezeIOBuffer

freezeIOBuffer :: Storable a => IOBuffer a -> IO (Boxed a) Source #

Lock and copy pinned IO values to a strict immutable boxed container. The result is independent of later buffer writes; allocation/IO exceptions propagate.

ioBufferLength

ioBufferLength :: IOBuffer a -> Int Source #

Return the immutable element count of a pinned IO buffer. This query neither borrows its pointer nor takes ownership.

readIOBuffer

readIOBuffer :: Storable a => IOBuffer a -> Int -> IO (Either MathError a) Source #

Given IO buffer then zero-based index, read under the buffer lock. Invalid index returns Left InvalidArgument; IO exceptions propagate.

writeIOBuffer

writeIOBuffer :: Storable a => IOBuffer a -> Int -> a -> IO (Either MathError ()) Source #

Given IO buffer, zero-based index, then value, write under its lock and return Right (). Invalid index returns Left InvalidArgument without modification.

withIOBuffer

withIOBuffer :: Storable a => IOBuffer a -> (Ptr a -> Int -> IO b) -> IO b Source #

Given IO buffer then callback, hold its lock and lend a Ptr plus element count for the callback duration. Do not retain the pointer or reenter locking operations on this same buffer. Callback exceptions propagate while releasing the lock.

unboxedToBoxed

unboxedToBoxed :: UnboxedDouble -> Boxed Double Source #

Convert unboxed Double storage to a new strict boxed container, preserving order and values.

boxedToUnboxed

boxedToUnboxed :: Boxed Double -> UnboxedDouble Source #

Convert boxed Double values to a new unboxed array, forcing values during copying. Preserve order and length.