ST package:ghc-internal

This library provides support for strict state threads, as described in the PLDI '94 paper by John Launchbury and Simon Peyton Jones Lazy Functional State Threads. References (variables) that can be used within the ST monad are provided by Data.STRef, and arrays are provided by Data.Array.ST.

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) = _|_

The lazy 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 executes 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 not strict in the state. For example,

runST (writeSTRef _|_ v >>= readSTRef _|_ >> return 2) = 2

The ST Monad.

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) = _|_

Mutable, boxed, non-strict arrays in the ST monad. The type arguments are as follows:

• s: the state variable argument for the ST type
• i: the index type of the array (should be an instance of Ix)
• e: the element type of the array.

Haskell representation of a StgStack* that was created (cloned) with a function in GHC.Stack.CloneStack. Please check the documentation in that module for more detailed explanations.

State# is the primitive, unlifted type of states. It has one type parameter, thus State# RealWorld, or State# s, where s is a type variable. The only purpose of the type parameter is to keep different state threads separate. It is represented by nothing at all.

String is an alias for a list of characters. String constants in Haskell are values of type String. That means if you write a string literal like "hello world", it will have the type [Char], which is the same as String. Note: You can ask the compiler to automatically infer different types with the -XOverloadedStrings language extension, for example "hello world" :: Text. See IsString for more information. Because String is just a list of characters, you can use normal list functions to do basic string manipulation. See Data.List for operations on lists.

Performance considerations

[Char] is a relatively memory-inefficient type. It is a linked list of boxed word-size characters, internally it looks something like:

╭─────┬───┬──╮  ╭─────┬───┬──╮  ╭─────┬───┬──╮  ╭────╮
│ (:) │   │ ─┼─>│ (:) │   │ ─┼─>│ (:) │   │ ─┼─>│ [] │
╰─────┴─┼─┴──╯  ╰─────┴─┼─┴──╯  ╰─────┴─┼─┴──╯  ╰────╯
v               v               v
'a'             'b'             'c'

The String "abc" will use 5*3+1 = 16 (in general 5n+1) words of space in memory. Furthermore, operations like (++) (string concatenation) are O(n) (in the left argument). For historical reasons, the base library uses String in a lot of places for the conceptual simplicity, but library code dealing with user-data should use the text package for Unicode text, or the the bytestring package for binary data.

A monad supporting atomic memory transactions.

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 transformer monad parameterized by the state and inner monad. The implementation is copied from the transformers package with the return tuple swapped.

Mutable references in the (strict) ST monad.