ST package:protolude

The strict ST monad. The ST monad allows for destructive updates, but is escapable (unlike IO). A computation of type ST s a returns a value of type a, and execute in "thread" s. The s parameter is either

• an uninstantiated type variable (inside invocations of runST), or
• RealWorld (inside invocations of stToIO).

It serves to keep the internal states of different invocations of runST separate from each other and from invocations of stToIO. The >>= and >> operations are strict in the state (though not in values stored in the state). For example,

runST (writeSTRef _|_ v >>= f) = _|_

A stable pointer is a reference to a Haskell expression that is guaranteed not to be affected by garbage collection, i.e., it will neither be deallocated nor will the value of the stable pointer itself change during garbage collection (ordinary references may be relocated during garbage collection). Consequently, stable pointers can be passed to foreign code, which can treat it as an opaque reference to a Haskell value. The StablePtr 0 is reserved for representing NULL in foreign code. A value of type StablePtr a is a stable pointer to a Haskell expression of type a.

The current thread's stack exceeded its limit. Since an exception has been raised, the thread's stack will certainly be below its limit again, but the programmer should take remedial action immediately.

A state monad parameterized by the type s of the state to carry. The return function leaves the state unchanged, while >>= uses the final state of the first computation as the initial state of the second.

A state transformer monad parameterized by:

• s - The state.
• m - The inner monad.

The return function leaves the state unchanged, while >>= uses the final state of the first computation as the initial state of the second.

A reference to a value of type a.

The member functions of this class facilitate writing values of primitive types to raw memory (which may have been allocated with the above mentioned routines) and reading values from blocks of raw memory. The class, furthermore, includes support for computing the storage requirements and alignment restrictions of storable types. Memory addresses are represented as values of type Ptr a, for some a which is an instance of class Storable. The type argument to Ptr helps provide some valuable type safety in FFI code (you can't mix pointers of different types without an explicit cast), while helping the Haskell type system figure out which marshalling method is needed for a given pointer. All marshalling between Haskell and a foreign language ultimately boils down to translating Haskell data structures into the binary representation of a corresponding data structure of the foreign language and vice versa. To code this marshalling in Haskell, it is necessary to manipulate primitive data types stored in unstructured memory blocks. The class Storable facilitates this manipulation on all types for which it is instantiated, which are the standard basic types of Haskell, the fixed size Int types (Int8, Int16, Int32, Int64), the fixed size Word types (Word8, Word16, Word32, Word64), StablePtr, all types from Foreign.C.Types, as well as Ptr.

Embed a simple state action into the monad.

Repeat a value n times. The default definition will raise an exception for a multiplier that is <= 0. This may be overridden with an implementation that is total. For monoids it is preferred to use stimesMonoid. By making this a member of the class, idempotent semigroups and monoids can upgrade this to execute in <math> by picking stimes = stimesIdempotent or stimes = stimesIdempotentMonoid respectively.

Examples

>>> stimes 4 [1]
[1,1,1,1]

>>> stimes 5 (putStr "hi!")
hi!hi!hi!hi!hi!

>>> stimes 3 (Right ":)")
Right ":)"

This is a valid definition of stimes for an idempotent Semigroup. When x <> x = x, this definition should be preferred, because it works in <math> rather than <math>.

This is a valid definition of stimes for an idempotent Monoid. When x <> x = x, this definition should be preferred, because it works in <math> rather than <math>

This is a valid definition of stimes for a Monoid. Unlike the default definition of stimes, it is defined for 0 and so it should be preferred where possible.

Throw a UnicodeException if decoding fails.

The thread is waiting to retry an STM transaction, but there are no other references to any TVars involved, so it can't ever continue.

A space-efficient representation of a Word8 vector, supporting many efficient operations. A ByteString contains 8-bit bytes, or by using the operations from Data.ByteString.Char8 it can be interpreted as containing 8-bit characters.

CallStacks are a lightweight method of obtaining a partial call-stack at any point in the program. A function can request its call-site with the HasCallStack constraint. For example, we can define

putStrLnWithCallStack :: HasCallStack => String -> IO ()

as a variant of putStrLn that will get its call-site and print it, along with the string given as argument. We can access the call-stack inside putStrLnWithCallStack with callStack.

>>> :{
putStrLnWithCallStack :: HasCallStack => String -> IO ()
putStrLnWithCallStack msg = do
putStrLn msg
putStrLn (prettyCallStack callStack)
:}

Thus, if we call putStrLnWithCallStack we will get a formatted call-stack alongside our string.

>>> putStrLnWithCallStack "hello"
hello
CallStack (from HasCallStack):
putStrLnWithCallStack, called at <interactive>:... in interactive:Ghci...

GHC solves HasCallStack constraints in three steps:

1. If there is a CallStack in scope -- i.e. the enclosing function has a HasCallStack constraint -- GHC will append the new call-site to the existing CallStack.
2. If there is no CallStack in scope -- e.g. in the GHCi session above -- and the enclosing definition does not have an explicit type signature, GHC will infer a HasCallStack constraint for the enclosing definition (subject to the monomorphism restriction).
3. If there is no CallStack in scope and the enclosing definition has an explicit type signature, GHC will solve the HasCallStack constraint for the singleton CallStack containing just the current call-site.

CallStacks do not interact with the RTS and do not require compilation with -prof. On the other hand, as they are built up explicitly via the HasCallStack constraints, they will generally not contain as much information as the simulated call-stacks maintained by the RTS. A CallStack is a [(String, SrcLoc)]. The String is the name of function that was called, the SrcLoc is the call-site. The list is ordered with the most recently called function at the head. NOTE: The intrepid user may notice that HasCallStack is just an alias for an implicit parameter ?callStack :: CallStack. This is an implementation detail and should not be considered part of the CallStack API, we may decide to change the implementation in the future.

The Const functor.