base-4.10.1.0: Basic libraries

Safe Haskell | Trustworthy
Language | Haskell2010

GHC.Stats

Contents

- Runtime statistics
- DEPRECATED, don't use

Description

This module provides access to internal garbage collection and memory usage statistics. These statistics are not available unless a program is run with the `-T` RTS flag.

This module is GHC-only and should not be considered portable.

Since: 4.5.0.0

Synopsis

- data RTSStats = RTSStats {
  - gcs :: Word32
  - major_gcs :: Word32
  - allocated_bytes :: Word64
  - max_live_bytes :: Word64
  - max_large_objects_bytes :: Word64
  - max_compact_bytes :: Word64
  - max_slop_bytes :: Word64
  - max_mem_in_use_bytes :: Word64
  - cumulative_live_bytes :: Word64
  - copied_bytes :: Word64
  - par_copied_bytes :: Word64
  - cumulative_par_max_copied_bytes :: Word64
  - mutator_cpu_ns :: RtsTime
  - mutator_elapsed_ns :: RtsTime
  - gc_cpu_ns :: RtsTime
  - gc_elapsed_ns :: RtsTime
  - cpu_ns :: RtsTime
  - elapsed_ns :: RtsTime
  - gc :: GCDetails
  }
- data GCDetails = GCDetails {
  - gcdetails_gen :: Word32
  - gcdetails_threads :: Word32
  - gcdetails_allocated_bytes :: Word64
  - gcdetails_live_bytes :: Word64
  - gcdetails_large_objects_bytes :: Word64
  - gcdetails_compact_bytes :: Word64
  - gcdetails_slop_bytes :: Word64
  - gcdetails_mem_in_use_bytes :: Word64
  - gcdetails_copied_bytes :: Word64
  - gcdetails_par_max_copied_bytes :: Word64
  - gcdetails_sync_elapsed_ns :: RtsTime
  - gcdetails_cpu_ns :: RtsTime
  - gcdetails_elapsed_ns :: RtsTime
  }
- type RtsTime = Int64
- getRTSStats :: IO RTSStats
- getRTSStatsEnabled :: IO Bool
- data GCStats = GCStats {
  - bytesAllocated :: !Int64
  - numGcs :: !Int64
  - maxBytesUsed :: !Int64
  - numByteUsageSamples :: !Int64
  - cumulativeBytesUsed :: !Int64
  - bytesCopied :: !Int64
  - currentBytesUsed :: !Int64
  - currentBytesSlop :: !Int64
  - maxBytesSlop :: !Int64
  - peakMegabytesAllocated :: !Int64
  - mblocksAllocated :: !Int64
  - mutatorCpuSeconds :: !Double
  - mutatorWallSeconds :: !Double
  - gcCpuSeconds :: !Double
  - gcWallSeconds :: !Double
  - cpuSeconds :: !Double
  - wallSeconds :: !Double
  - parTotBytesCopied :: !Int64
  - parMaxBytesCopied :: !Int64
  }
- getGCStats :: IO GCStats
- getGCStatsEnabled :: IO Bool

# Runtime statistics

data RTSStats #

Statistics about runtime activity since the start of the program. This is a mirror of the C `struct RTSStats` in `RtsAPI.h`

Since: 4.9.0.0

Constructors

RTSStats |

Fields

- gcs :: Word32

  Total number of GCs

- major_gcs :: Word32

  Total number of major (oldest generation) GCs

- allocated_bytes :: Word64

  Total bytes allocated

- max_live_bytes :: Word64

  Maximum live data (including large objects + compact regions)

- max_large_objects_bytes :: Word64

  Maximum live data in large objects

- max_compact_bytes :: Word64

  Maximum live data in compact regions

- max_slop_bytes :: Word64

  Maximum slop

- max_mem_in_use_bytes :: Word64

  Maximum memory in use by the RTS

- cumulative_live_bytes :: Word64

  Sum of live bytes across all major GCs. Divided by major_gcs gives the average live data over the lifetime of the program.

- copied_bytes :: Word64

  Sum of copied_bytes across all GCs

- par_copied_bytes :: Word64

  Sum of copied_bytes across all parallel GCs

- cumulative_par_max_copied_bytes :: Word64

  Sum of par_max_copied_bytes across all parallel GCs

- mutator_cpu_ns :: RtsTime

  Total CPU time used by the mutator

- mutator_elapsed_ns :: RtsTime

  Total elapsed time used by the mutator

- gc_cpu_ns :: RtsTime

  Total CPU time used by the GC

- gc_elapsed_ns :: RtsTime

  Total elapsed time used by the GC

- cpu_ns :: RtsTime

  Total CPU time (at the previous GC)

- elapsed_ns :: RtsTime

  Total elapsed time (at the previous GC)

- gc :: GCDetails

  Details about the most recent GC

Instances

Read RTSStats # |
Methods readsPrec :: Int -> ReadS RTSStats # readList :: ReadS [RTSStats] # readPrec :: ReadPrec RTSStats # readListPrec :: ReadPrec [RTSStats] #
Show RTSStats # |
Methods showsPrec :: Int -> RTSStats -> ShowS # show :: RTSStats -> String # showList :: [RTSStats] -> ShowS #

data GCDetails #

Statistics about a single GC. This is a mirror of the C `struct GCDetails` in `RtsAPI.h`, with the field prefixed with `gc_` to avoid collisions with `RTSStats`.

Constructors

GCDetails |

Fields

- gcdetails_gen :: Word32

  The generation number of this GC

- gcdetails_threads :: Word32

  Number of threads used in this GC

- gcdetails_allocated_bytes :: Word64

  Number of bytes allocated since the previous GC

- gcdetails_live_bytes :: Word64

  Total amount of live data in the heap (incliudes large + compact data)

- gcdetails_large_objects_bytes :: Word64

  Total amount of live data in large objects

- gcdetails_compact_bytes :: Word64

  Total amount of live data in compact regions

- gcdetails_slop_bytes :: Word64

  Total amount of slop (wasted memory)

- gcdetails_mem_in_use_bytes :: Word64

  Total amount of memory in use by the RTS

- gcdetails_copied_bytes :: Word64

  Total amount of data copied during this GC

- gcdetails_par_max_copied_bytes :: Word64

  In parallel GC, the max amount of data copied by any one thread

- gcdetails_sync_elapsed_ns :: RtsTime

  The time elapsed during synchronisation before GC

- gcdetails_cpu_ns :: RtsTime

  The CPU time used during GC itself

- gcdetails_elapsed_ns :: RtsTime

  The time elapsed during GC itself

Instances

Read GCDetails # |
Methods readsPrec :: Int -> ReadS GCDetails # readList :: ReadS [GCDetails] # readPrec :: ReadPrec GCDetails # readListPrec :: ReadPrec [GCDetails] #
Show GCDetails # |
Methods showsPrec :: Int -> GCDetails -> ShowS # show :: GCDetails -> String # showList :: [GCDetails] -> ShowS #

type RtsTime = Int64 #

Time values from the RTS, using a fixed resolution of nanoseconds.

getRTSStats :: IO RTSStats #

getRTSStatsEnabled :: IO Bool #

Returns whether GC stats have been enabled (with `+RTS -T`, for example).

Since: 4.9.0.0

# DEPRECATED, don't use

data GCStats #

Deprecated: Use RTSStats instead. This will be removed in GHC 8.4.1

Statistics about memory usage and the garbage collector. Apart from `currentBytesUsed` and `currentBytesSlop` all are cumulative values since the program started.

Since: 4.5.0.0

Constructors

GCStats | Deprecated: Use RTSStats instead. This will be removed in GHC 8.4.1

Fields

- bytesAllocated :: !Int64

  Total number of bytes allocated

- numGcs :: !Int64

  Number of garbage collections performed (any generation, major and minor)

- maxBytesUsed :: !Int64

  Maximum number of live bytes seen so far

- numByteUsageSamples :: !Int64

  Number of byte usage samples taken, or equivalently the number of major GCs performed.

- cumulativeBytesUsed :: !Int64

  Sum of all byte usage samples, can be used with `numByteUsageSamples` to calculate averages with arbitrary weighting (if you are sampling this record multiple times).

- bytesCopied :: !Int64

  Number of bytes copied during GC

- currentBytesUsed :: !Int64

  Number of live bytes at the end of the last major GC

- currentBytesSlop :: !Int64

  Current number of bytes lost to slop

- maxBytesSlop :: !Int64

  Maximum number of bytes lost to slop at any one time so far

- peakMegabytesAllocated :: !Int64

  Maximum number of megabytes allocated

- mblocksAllocated :: !Int64

  Number of allocated megablocks

- mutatorCpuSeconds :: !Double
- mutatorWallSeconds :: !Double

  Wall clock time spent running mutator threads. This does not include initialization.

- gcCpuSeconds :: !Double

  CPU time spent running GC

- gcWallSeconds :: !Double

  Wall clock time spent running GC

- cpuSeconds :: !Double

  Total CPU time elapsed since program start

- wallSeconds :: !Double

  Total wall clock time elapsed since start

- parTotBytesCopied :: !Int64

  Number of bytes copied during GC, minus space held by mutable lists held by the capabilities. Can be used with `parMaxBytesCopied` to determine how well parallel GC utilized all cores.

- parMaxBytesCopied :: !Int64

  Sum of number of bytes copied each GC by the most active GC thread each GC. The ratio of `parTotBytesCopied` divided by `parMaxBytesCopied` approaches 1 for a maximally sequential run and approaches the number of threads (set by the RTS flag `-N`) for a maximally parallel run.

Instances

Read GCStats # |
Methods readsPrec :: Int -> ReadS GCStats # readList :: ReadS [GCStats] # readPrec :: ReadPrec GCStats # readListPrec :: ReadPrec [GCStats] #
Show GCStats # |
Methods showsPrec :: Int -> GCStats -> ShowS # show :: GCStats -> String # showList :: [GCStats] -> ShowS #

getGCStats :: IO GCStats #

Deprecated: Use getRTSStats instead. This will be removed in GHC 8.4.1

Retrieves garbage collection and memory statistics as of the last garbage collection. If you would like your statistics as recent as possible, first run a `performGC`.

Since: 4.5.0.0

getGCStatsEnabled :: IO Bool #

Deprecated: use getRTSStatsEnabled instead. This will be removed in GHC 8.4.1