GHC.Runtime.Heap.Layout

ghc-lib-parser-9.14.1.20251220: The GHC API, decoupled from GHC versions

Safe Haskell | Ignore
Language | GHC2021

GHC.Runtime.Heap.Layout

Contents

- Words and bytes
- Closure representation
  - Construction
  - Predicates
  - Size-related things
  - RTS closure types
  - Arrays

Synopsis

- type WordOff = Int
- type ByteOff = Int
- wordsToBytes :: Num a => Platform -> a -> a
- bytesToWordsRoundUp :: Platform -> ByteOff -> WordOff
- roundUpToWords :: Platform -> ByteOff -> ByteOff
- roundUpTo :: ByteOff -> ByteOff -> ByteOff
- data StgWord
- fromStgWord :: StgWord -> Integer
- toStgWord :: Platform -> Integer -> StgWord
- data StgHalfWord
- fromStgHalfWord :: StgHalfWord -> Integer
- toStgHalfWord :: Platform -> Integer -> StgHalfWord
- halfWordSize :: Platform -> ByteOff
- halfWordSizeInBits :: Platform -> Int
- data SMRep
  - = HeapRep IsStatic !WordOff !WordOff ClosureTypeInfo
  - | ArrayPtrsRep !WordOff !WordOff
  - | SmallArrayPtrsRep !WordOff
  - | ArrayWordsRep !WordOff
  - | StackRep Liveness
  - | RTSRep Int SMRep
- type IsStatic = Bool
- data ClosureTypeInfo
  - = Constr ConTagZ ConstrDescription
  - | Fun FunArity ArgDescr
  - | Thunk
  - | ThunkSelector SelectorOffset
  - | BlackHole
  - | IndStatic
- data ArgDescr
  - = ArgSpec !Int
  - | ArgGen Liveness
  - | ArgUnknown
- type Liveness = [Bool]
- type ConstrDescription = ByteString
- mkHeapRep :: Profile -> IsStatic -> WordOff -> WordOff -> ClosureTypeInfo -> SMRep
- blackHoleRep :: SMRep
- indStaticRep :: SMRep
- mkStackRep :: [Bool] -> SMRep
- mkRTSRep :: Int -> SMRep -> SMRep
- arrPtrsRep :: Platform -> WordOff -> SMRep
- smallArrPtrsRep :: WordOff -> SMRep
- arrWordsRep :: Platform -> ByteOff -> SMRep
- isStaticRep :: SMRep -> IsStatic
- isConRep :: SMRep -> Bool
- isThunkRep :: SMRep -> Bool
- isFunRep :: SMRep -> Bool
- isStaticNoCafCon :: SMRep -> Bool
- isStackRep :: SMRep -> Bool
- heapClosureSizeW :: Profile -> SMRep -> WordOff
- fixedHdrSizeW :: Profile -> WordOff
- arrWordsHdrSize :: Profile -> ByteOff
- arrWordsHdrSizeW :: Profile -> WordOff
- arrPtrsHdrSize :: Profile -> ByteOff
- arrPtrsHdrSizeW :: Profile -> WordOff
- profHdrSize :: Profile -> WordOff
- thunkHdrSize :: Profile -> WordOff
- nonHdrSize :: Platform -> SMRep -> ByteOff
- nonHdrSizeW :: SMRep -> WordOff
- smallArrPtrsHdrSize :: Profile -> ByteOff
- smallArrPtrsHdrSizeW :: Profile -> WordOff
- hdrSize :: Profile -> SMRep -> ByteOff
- hdrSizeW :: Profile -> SMRep -> WordOff
- fixedHdrSize :: Profile -> ByteOff
- rtsClosureType :: SMRep -> Int
- rET_SMALL :: Int
- rET_BIG :: Int
- aRG_GEN :: Int
- aRG_GEN_BIG :: Int
- card :: Platform -> Int -> Int
- cardRoundUp :: Platform -> Int -> Int
- cardTableSizeB :: Platform -> Int -> ByteOff
- cardTableSizeW :: Platform -> Int -> WordOff

# Words and bytes

type WordOff = Int #

Word offset, or word count

type ByteOff = Int #

Byte offset, or byte count

wordsToBytes :: Num a => Platform -> a -> a #

Convert the given number of words to a number of bytes.

This function morally has type `WordOff -> ByteOff`, but uses `Num a` to allow for overloading.

bytesToWordsRoundUp :: Platform -> ByteOff -> WordOff #

First round the given byte count up to a multiple of the machine's word size and then convert the result to words.

roundUpToWords :: Platform -> ByteOff -> ByteOff #

Round up the given byte count to the next byte count that's a multiple of the machine's word size.

roundUpTo :: ByteOff -> ByteOff -> ByteOff #

Round up `base` to a multiple of `size`.

data StgWord #

#### Instances

Instances details

Bits StgWord # |
Instance details Defined in GHC.Runtime.Heap.Layout Methods (.&.) :: StgWord -> StgWord -> StgWord # (.|.) :: StgWord -> StgWord -> StgWord # xor :: StgWord -> StgWord -> StgWord # complement :: StgWord -> StgWord # shift :: StgWord -> Int -> StgWord # rotate :: StgWord -> Int -> StgWord # zeroBits :: StgWord # bit :: Int -> StgWord # setBit :: StgWord -> Int -> StgWord # clearBit :: StgWord -> Int -> StgWord # complementBit :: StgWord -> Int -> StgWord # testBit :: StgWord -> Int -> Bool # bitSizeMaybe :: StgWord -> Maybe Int # bitSize :: StgWord -> Int # isSigned :: StgWord -> Bool # shiftL :: StgWord -> Int -> StgWord # unsafeShiftL :: StgWord -> Int -> StgWord # shiftR :: StgWord -> Int -> StgWord # unsafeShiftR :: StgWord -> Int -> StgWord # rotateL :: StgWord -> Int -> StgWord # rotateR :: StgWord -> Int -> StgWord # popCount :: StgWord -> Int #
Outputable StgWord # |
Instance details Defined in GHC.Runtime.Heap.Layout Methods ppr :: StgWord -> SDoc #
Eq StgWord # |
Instance details Defined in GHC.Runtime.Heap.Layout Methods (==) :: StgWord -> StgWord -> Bool # (/=) :: StgWord -> StgWord -> Bool #

fromStgWord :: StgWord -> Integer #

toStgWord :: Platform -> Integer -> StgWord #

data StgHalfWord #

#### Instances

Instances details

Outputable StgHalfWord # |
Instance details Defined in GHC.Runtime.Heap.Layout Methods ppr :: StgHalfWord -> SDoc #
Eq StgHalfWord # |
Instance details Defined in GHC.Runtime.Heap.Layout Methods (==) :: StgHalfWord -> StgHalfWord -> Bool # (/=) :: StgHalfWord -> StgHalfWord -> Bool #

fromStgHalfWord :: StgHalfWord -> Integer #

toStgHalfWord :: Platform -> Integer -> StgHalfWord #

halfWordSize :: Platform -> ByteOff #

Half word size in bytes

halfWordSizeInBits :: Platform -> Int #

# Closure representation

data SMRep #

A description of the layout of a closure. Corresponds directly to the closure types in includes/rts/storage/ClosureTypes.h.

Constructors

HeapRep IsStatic !WordOff !WordOff ClosureTypeInfo |
ArrayPtrsRep !WordOff !WordOff |
SmallArrayPtrsRep !WordOff |
ArrayWordsRep !WordOff |
StackRep Liveness |
RTSRep Int SMRep |

#### Instances

Instances details

Outputable SMRep # |
Instance details Defined in GHC.Runtime.Heap.Layout Methods ppr :: SMRep -> SDoc #
Eq SMRep # |
Instance details Defined in GHC.Runtime.Heap.Layout Methods (==) :: SMRep -> SMRep -> Bool # (/=) :: SMRep -> SMRep -> Bool #
Ord SMRep # |
Instance details Defined in GHC.Runtime.Heap.Layout Methods compare :: SMRep -> SMRep -> Ordering # (<) :: SMRep -> SMRep -> Bool # (<=) :: SMRep -> SMRep -> Bool # (>) :: SMRep -> SMRep -> Bool # (>=) :: SMRep -> SMRep -> Bool # max :: SMRep -> SMRep -> SMRep # min :: SMRep -> SMRep -> SMRep #

type IsStatic = Bool #

True <=> This is a static closure. Affects how we garbage-collect it. Static closure have an extra static link field at the end. Constructors do not have a static variant; see Note [static constructors]

data ClosureTypeInfo #

Constructors

Constr ConTagZ ConstrDescription |
Fun FunArity ArgDescr |
Thunk |
ThunkSelector SelectorOffset |
BlackHole |
IndStatic |

#### Instances

Instances details

Outputable ClosureTypeInfo # |
Instance details Defined in GHC.Runtime.Heap.Layout Methods ppr :: ClosureTypeInfo -> SDoc #
Eq ClosureTypeInfo # |
Instance details Defined in GHC.Runtime.Heap.Layout Methods (==) :: ClosureTypeInfo -> ClosureTypeInfo -> Bool # (/=) :: ClosureTypeInfo -> ClosureTypeInfo -> Bool #
Ord ClosureTypeInfo # |
Instance details Defined in GHC.Runtime.Heap.Layout Methods compare :: ClosureTypeInfo -> ClosureTypeInfo -> Ordering # (<) :: ClosureTypeInfo -> ClosureTypeInfo -> Bool # (<=) :: ClosureTypeInfo -> ClosureTypeInfo -> Bool # (>) :: ClosureTypeInfo -> ClosureTypeInfo -> Bool # (>=) :: ClosureTypeInfo -> ClosureTypeInfo -> Bool # max :: ClosureTypeInfo -> ClosureTypeInfo -> ClosureTypeInfo # min :: ClosureTypeInfo -> ClosureTypeInfo -> ClosureTypeInfo #

data ArgDescr #

An ArgDescr describes the argument pattern of a function

Constructors

ArgSpec !Int |
ArgGen Liveness |
ArgUnknown |

#### Instances

Instances details

Outputable ArgDescr # |
Instance details Defined in GHC.Runtime.Heap.Layout Methods ppr :: ArgDescr -> SDoc #
Eq ArgDescr # |
Instance details Defined in GHC.Runtime.Heap.Layout Methods (==) :: ArgDescr -> ArgDescr -> Bool # (/=) :: ArgDescr -> ArgDescr -> Bool #
Ord ArgDescr # |
Instance details Defined in GHC.Runtime.Heap.Layout Methods compare :: ArgDescr -> ArgDescr -> Ordering # (<) :: ArgDescr -> ArgDescr -> Bool # (<=) :: ArgDescr -> ArgDescr -> Bool # (>) :: ArgDescr -> ArgDescr -> Bool # (>=) :: ArgDescr -> ArgDescr -> Bool # max :: ArgDescr -> ArgDescr -> ArgDescr # min :: ArgDescr -> ArgDescr -> ArgDescr #

type Liveness = [Bool] #

We represent liveness bitmaps as a Bitmap (whose internal representation really is a bitmap). These are pinned onto case return vectors to indicate the state of the stack for the garbage collector.

In the compiled program, liveness bitmaps that fit inside a single word (StgWord) are stored as a single word, while larger bitmaps are stored as a pointer to an array of words.

type ConstrDescription = ByteString #

## Construction

mkHeapRep :: Profile -> IsStatic -> WordOff -> WordOff -> ClosureTypeInfo -> SMRep #

blackHoleRep :: SMRep #

indStaticRep :: SMRep #

mkStackRep :: [Bool] -> SMRep #

mkRTSRep :: Int -> SMRep -> SMRep #

arrPtrsRep :: Platform -> WordOff -> SMRep #

smallArrPtrsRep :: WordOff -> SMRep #

arrWordsRep :: Platform -> ByteOff -> SMRep #

## Predicates

isStaticRep :: SMRep -> IsStatic #

isConRep :: SMRep -> Bool #

isThunkRep :: SMRep -> Bool #

isFunRep :: SMRep -> Bool #

isStaticNoCafCon :: SMRep -> Bool #

isStackRep :: SMRep -> Bool #

## Size-related things

heapClosureSizeW :: Profile -> SMRep -> WordOff #

The total size of the closure, in words.

fixedHdrSizeW :: Profile -> WordOff #

Size of a closure header (StgHeader in includes/rts/storage/Closures.h)

arrWordsHdrSize :: Profile -> ByteOff #

arrWordsHdrSizeW :: Profile -> WordOff #

arrPtrsHdrSize :: Profile -> ByteOff #

arrPtrsHdrSizeW :: Profile -> WordOff #

profHdrSize :: Profile -> WordOff #

Size of the profiling part of a closure header (StgProfHeader in includes/rts/storage/Closures.h)

thunkHdrSize :: Profile -> WordOff #

nonHdrSize :: Platform -> SMRep -> ByteOff #

nonHdrSizeW :: SMRep -> WordOff #

smallArrPtrsHdrSize :: Profile -> ByteOff #

smallArrPtrsHdrSizeW :: Profile -> WordOff #

hdrSize :: Profile -> SMRep -> ByteOff #

hdrSizeW :: Profile -> SMRep -> WordOff #

fixedHdrSize :: Profile -> ByteOff #

## RTS closure types

rtsClosureType :: SMRep -> Int #

Derives the RTS closure type from an `SMRep`

rET_SMALL :: Int #

rET_BIG :: Int #

aRG_GEN :: Int #

aRG_GEN_BIG :: Int #

## Arrays

card :: Platform -> Int -> Int #

The byte offset into the card table of the card for a given element

cardRoundUp :: Platform -> Int -> Int #

Convert a number of elements to a number of cards, rounding up

cardTableSizeB :: Platform -> Int -> ByteOff #

The size of a card table, in bytes

cardTableSizeW :: Platform -> Int -> WordOff #

The size of a card table, in words