Documentation

Force all of the elements of a Foldable to weak head normal form.

In order to ensure that all of the elements of a Foldable are strict, we can simply foldMap over it and seq each value with (). However, ()'s mappend implementation is actually completely lazy: _ <> _ = () So, in order to work around this, we instead utilize this newly defined StrictUnit whose mappend implementation is specifically strict.

Attempt to parse a value of type a from the body of a JSString using parser

Size in the heap of values, in words (to get the size in bytes multiply by 4 on a 32-bit machine or 8 on a 64-bit machine)

These functions assume a 64-bit architecture

These functions assume a 64-bit architecture

Calculate the number of heap words used by a field unpacked within another constructor.

This function simply subtracts 2 from the heapWords result of its parameter, since in the case of an unpacked field we _do not_ have to use:

• a word for the pointer to the inner structure.
• a word for the constructor that is being unpacked.

Options which detail how a Closure Tree should be constructed.

Whether to traverse cyclic closures in a Closure Tree.

The depth of a Tree.

Given a Haskell expression, build a Tree which reflects its heap object representation.

Given a Haskell expression, build a Tree which reflects its heap object representation and render it as Text.

Should we perform a GC call before counting the size?

Compute the size of the given closure

This is a wrapper around computeHeapSize' which sets some defaults for the capacity of worklist and the visited set: it uses a worklist capacity of 10k (which, assuming balanced data structures, should be more than enough), an initial visited set capacity of 250k, and a maximum visited set capacity of 16M. This means that this will use between 2 MB and 128 MB of heaps space.

It also does NOT perform GC before counting, for improved performance. Client code can call performMajorGC manually or use computeHeapSize'.

Should these limits not be sufficient, or conversely, the memory requirements be too large, use computeHeapSize' directly.

Compute the size of the given closure

The size of the worklist should be set to the maximum expected depth of the closure; the size of the visited set should be set to the maximum /number of nodes/ in the closure.

computeHeapSizeWorkList can be used to estimate the size of the worklist required.

Upper bound on the required work list size to compute closure size

NOTE: This ignores sharing, and so provides an upper bound only.

The size of a closure with no nested pointers can be computed without any stack space.

When we have a closure with (N + 1) nested pointers

p0 p1 .. pN

We will

• Push pN, .., p1, p0 onto the stack
• Pop off p0 and count its children
• Pop off p1 and count its children
• ..

until we have processed all children. This means that the stack space required will be the maximum of

[ N + 1 -- For the initial list
, requiredWorkList p0 + (N + 1) - 1
, requiredWorkList p1 + (N + 1) - 2
, ..
, requiredWorkList pN + (N + 1) - (N + 1)
]

For example, for a list, we would get that

requiredWorkList []     == 0
requiredWorkList (x:xs) == max [ 2
                               , requiredWorkList x + 1
                               , requiredWorkList xs
                               ]

which, for a list of Int (which requires only a stack of size 1), equals 2 (unless the list is empty).

Similarly, for binary trees, we get

requiredWorkList Leaf           == 0
requiredWorkList (Branch l x r) == max [ 3
                                       , requiredWorkList l + 2
                                       , requiredWorkList x + 1
                                       , requiredWorkList r
                                       ]

which, for a tree of Int, is bound by (height * 2) + 1.

The function isNormalForm checks whether its argument is fully evaluated and deeply evaluated.

NOTE: The normal form check can be quite brittle, especially with -O0. For example, writing something like

let !(Value x) = ... in ....

might translate to

let !.. = ... in ... (case ... of Value x -> x)

which would trivially be False. In general, isNormalForm should probably only be used with -O1, but even then the answer may still depend on internal decisions made by ghc during compilation.

A Builder for a ByteString that performs base 16 encoding

A Format for a ByteString that performs base 16 encoding

A Format for a pair of Buildable values (a, b)

A Builder for a pair of Buildable values (a, b)

A Format for Foldable containers that outputs a JSON-style list

A Format similar to listJson that prints each value on a new line with indent spaces of indentation

A Format for Exts.IsList containers of Buildable key-value pairs that outputs a JSON-style colon-separated map

Convert an Either-encoded error to an aeson parser error

Convert a Buildable error into an aeson parser error

Convert an Either-encoded failure to a cborg decoder failure

Convert a Buildable error into a cborg decoder error

A helper for lifting an Either to a MonadError

By using this function infix we can move the error handling to the end of an expression, hopefully improving readability.

A helper for lifting unless to MonadError

By using this function infix we can move error handling to the end of a Bool expression, hopefully improving readability.

Append two lists, i.e.,

[x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
[x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]

If the first list is not finite, the result is the first list.

The value of seq a b is bottom if a is bottom, and otherwise equal to b. In other words, it evaluates the first argument a to weak head normal form (WHNF). seq is usually introduced to improve performance by avoiding unneeded laziness.

A note on evaluation order: the expression seq a b does not guarantee that a will be evaluated before b. The only guarantee given by seq is that the both a and b will be evaluated before seq returns a value. In particular, this means that b may be evaluated before a. If you need to guarantee a specific order of evaluation, you must use the function pseq from the "parallel" package.

\(\mathcal{O}(n)\). filter, applied to a predicate and a list, returns the list of those elements that satisfy the predicate; i.e.,

filter p xs = [ x | x <- xs, p x]

>>> filter odd [1, 2, 3]
[1,3]

\(\mathcal{O}(\min(m,n))\). zip takes two lists and returns a list of corresponding pairs.

zip [1, 2] ['a', 'b'] = [(1, 'a'), (2, 'b')]

If one input list is short, excess elements of the longer list are discarded:

zip [1] ['a', 'b'] = [(1, 'a')]
zip [1, 2] ['a'] = [(1, 'a')]

zip is right-lazy:

zip [] _|_ = []
zip _|_ [] = _|_

zip is capable of list fusion, but it is restricted to its first list argument and its resulting list.

Extract the first component of a pair.

Extract the second component of a pair.

otherwise is defined as the value True. It helps to make guards more readable. eg.

 f x | x < 0     = ...
     | otherwise = ...

Application operator. This operator is redundant, since ordinary application (f x) means the same as (f $ x). However, $ has low, right-associative binding precedence, so it sometimes allows parentheses to be omitted; for example:

f $ g $ h x  =  f (g (h x))

It is also useful in higher-order situations, such as map ($ 0) xs, or zipWith ($) fs xs.

Note that ($) is levity-polymorphic in its result type, so that foo $ True where foo :: Bool -> Int# is well-typed.

general coercion from integral types

general coercion to fractional types

Conditional failure of Alternative computations. Defined by

guard True  = pure ()
guard False = empty

Examples

>>> safeDiv 4 0
Nothing
>>> safeDiv 4 2
Just 2

safeDiv :: Int -> Int -> Maybe Int
safeDiv x y | y /= 0    = Just (x `div` y)
            | otherwise = Nothing

safeDiv :: Int -> Int -> Maybe Int
safeDiv x y = do
  guard (y /= 0)
  return (x `div` y)

The join function is the conventional monad join operator. It is used to remove one level of monadic structure, projecting its bound argument into the outer level.

'join bss' can be understood as the do expression

do bs <- bss
   bs

Examples

atomically :: STM a -> IO a

atomically :: STM (IO b) -> IO (IO b)
join       :: IO (IO b)  -> IO b

join . atomically :: STM (IO b) -> IO b

The Bounded class is used to name the upper and lower limits of a type. Ord is not a superclass of Bounded since types that are not totally ordered may also have upper and lower bounds.

The Bounded class may be derived for any enumeration type; minBound is the first constructor listed in the data declaration and maxBound is the last. Bounded may also be derived for single-constructor datatypes whose constituent types are in Bounded.