c4e2e809f819f6c513780eb9cc9e764305de9151
[ghc.git] / libraries / base / GHC / Stats.hsc
1 {-# LANGUAGE Trustworthy #-}
2 {-# LANGUAGE NoImplicitPrelude #-}
3 {-# LANGUAGE RecordWildCards #-}
4 {-# OPTIONS_GHC -funbox-strict-fields #-}
5
6 -----------------------------------------------------------------------------
7 -- | This module provides access to internal garbage collection and
8 -- memory usage statistics.  These statistics are not available unless
9 -- a program is run with the @-T@ RTS flag.
10 --
11 -- This module is GHC-only and should not be considered portable.
12 --
13 -- @since 4.5.0.0
14 -----------------------------------------------------------------------------
15 module GHC.Stats
16     (
17     -- * Runtime statistics
18       RTSStats(..), GCDetails(..), RtsTime
19     , getRTSStats
20     , getRTSStatsEnabled
21
22     -- * DEPRECATED, don't use
23     , GCStats(..)
24     , getGCStats
25     , getGCStatsEnabled
26 ) where
27
28 import Control.Applicative
29 import Control.Monad
30 import Data.Int
31 import Data.Word
32 import GHC.Base
33 import GHC.Num (Num(..))
34 import GHC.Real (quot, fromIntegral, (/))
35 import GHC.Read ( Read )
36 import GHC.Show ( Show )
37 import GHC.IO.Exception
38 import Foreign.Marshal.Alloc
39 import Foreign.Storable
40 import Foreign.Ptr
41
42 #include "Rts.h"
43
44 foreign import ccall "getRTSStats" getRTSStats_ :: Ptr () -> IO ()
45
46 -- | Returns whether GC stats have been enabled (with @+RTS -T@, for example).
47 --
48 -- @since 4.9.0.0
49 foreign import ccall "getRTSStatsEnabled" getRTSStatsEnabled :: IO Bool
50
51 --
52 -- | Statistics about runtime activity since the start of the
53 -- program.  This is a mirror of the C @struct RTSStats@ in @RtsAPI.h@
54 --
55 -- @since 4.9.0.0
56 --
57 data RTSStats = RTSStats {
58   -- -----------------------------------
59   -- Cumulative stats about memory use
60
61     -- | Total number of GCs
62     gcs :: Word32
63     -- | Total number of major (oldest generation) GCs
64   , major_gcs :: Word32
65     -- | Total bytes allocated
66   , allocated_bytes :: Word64
67     -- | Maximum live data (including large objects + compact regions)
68   , max_live_bytes :: Word64
69     -- | Maximum live data in large objects
70   , max_large_objects_bytes :: Word64
71     -- | Maximum live data in compact regions
72   , max_compact_bytes :: Word64
73     -- | Maximum slop
74   , max_slop_bytes :: Word64
75     -- | Maximum memory in use by the RTS
76   , max_mem_in_use_bytes :: Word64
77     -- | Sum of live bytes across all major GCs.  Divided by major_gcs
78     -- gives the average live data over the lifetime of the program.
79   , cumulative_live_bytes :: Word64
80     -- | Sum of copied_bytes across all GCs
81   , copied_bytes :: Word64
82     -- | Sum of copied_bytes across all parallel GCs
83   , par_copied_bytes :: Word64
84     -- | Sum of par_max_copied_bytes across all parallel GCs
85   , cumulative_par_max_copied_bytes :: Word64
86
87   -- -----------------------------------
88   -- Cumulative stats about time use
89   -- (we use signed values here because due to inaccuracies in timers
90   -- the values can occasionally go slightly negative)
91
92     -- | Total CPU time used by the mutator
93   , mutator_cpu_ns :: RtsTime
94     -- | Total elapsed time used by the mutator
95   , mutator_elapsed_ns :: RtsTime
96     -- | Total CPU time used by the GC
97   , gc_cpu_ns :: RtsTime
98     -- | Total elapsed time used by the GC
99   , gc_elapsed_ns :: RtsTime
100     -- | Total CPU time (at the previous GC)
101   , cpu_ns :: RtsTime
102     -- | Total elapsed time (at the previous GC)
103   , elapsed_ns :: RtsTime
104
105     -- | Details about the most recent GC
106   , gc :: GCDetails
107   } deriving (Read, Show)
108
109 --
110 -- | Statistics about a single GC.  This is a mirror of the C @struct
111 --   GCDetails@ in @RtsAPI.h@, with the field prefixed with @gc_@ to
112 --   avoid collisions with 'RTSStats'.
113 --
114 data GCDetails = GCDetails {
115     -- | The generation number of this GC
116     gcdetails_gen :: Word32
117     -- | Number of threads used in this GC
118   , gcdetails_threads :: Word32
119     -- | Number of bytes allocated since the previous GC
120   , gcdetails_allocated_bytes :: Word64
121     -- | Total amount of live data in the heap (incliudes large + compact data)
122   , gcdetails_live_bytes :: Word64
123     -- | Total amount of live data in large objects
124   , gcdetails_large_objects_bytes :: Word64
125     -- | Total amount of live data in compact regions
126   , gcdetails_compact_bytes :: Word64
127     -- | Total amount of slop (wasted memory)
128   , gcdetails_slop_bytes :: Word64
129     -- | Total amount of memory in use by the RTS
130   , gcdetails_mem_in_use_bytes :: Word64
131     -- | Total amount of data copied during this GC
132   , gcdetails_copied_bytes :: Word64
133     -- | In parallel GC, the max amount of data copied by any one thread
134   , gcdetails_par_max_copied_bytes :: Word64
135     -- | The time elapsed during synchronisation before GC
136   , gcdetails_sync_elapsed_ns :: RtsTime
137     -- | The CPU time used during GC itself
138   , gcdetails_cpu_ns :: RtsTime
139     -- | The time elapsed during GC itself
140   , gcdetails_elapsed_ns :: RtsTime
141   } deriving (Read, Show)
142
143 -- | Time values from the RTS, using a fixed resolution of nanoseconds.
144 type RtsTime = Int64
145
146 -- @since 4.9.0.0
147 --
148 getRTSStats :: IO RTSStats
149 getRTSStats = do
150   statsEnabled <- getGCStatsEnabled
151   unless statsEnabled .  ioError $ IOError
152     Nothing
153     UnsupportedOperation
154     ""
155     "getGCStats: GC stats not enabled. Use `+RTS -T -RTS' to enable them."
156     Nothing
157     Nothing
158   allocaBytes (#size RTSStats) $ \p -> do
159     getRTSStats_ p
160     gcs <- (# peek RTSStats, gcs) p
161     major_gcs <- (# peek RTSStats, major_gcs) p
162     allocated_bytes <- (# peek RTSStats, allocated_bytes) p
163     max_live_bytes <- (# peek RTSStats, max_live_bytes) p
164     max_large_objects_bytes <- (# peek RTSStats, max_large_objects_bytes) p
165     max_compact_bytes <- (# peek RTSStats, max_compact_bytes) p
166     max_slop_bytes <- (# peek RTSStats, max_slop_bytes) p
167     max_mem_in_use_bytes <- (# peek RTSStats, max_mem_in_use_bytes) p
168     cumulative_live_bytes <- (# peek RTSStats, cumulative_live_bytes) p
169     copied_bytes <- (# peek RTSStats, copied_bytes) p
170     par_copied_bytes <- (# peek RTSStats, par_copied_bytes) p
171     cumulative_par_max_copied_bytes <-
172       (# peek RTSStats, cumulative_par_max_copied_bytes) p
173     mutator_cpu_ns <- (# peek RTSStats, mutator_cpu_ns) p
174     mutator_elapsed_ns <- (# peek RTSStats, mutator_elapsed_ns) p
175     gc_cpu_ns <- (# peek RTSStats, gc_cpu_ns) p
176     gc_elapsed_ns <- (# peek RTSStats, gc_elapsed_ns) p
177     cpu_ns <- (# peek RTSStats, cpu_ns) p
178     elapsed_ns <- (# peek RTSStats, elapsed_ns) p
179     let pgc = (# ptr RTSStats, gc) p
180     gc <- do
181       gcdetails_gen <- (# peek GCDetails, gen) pgc
182       gcdetails_threads <- (# peek GCDetails, threads) pgc
183       gcdetails_allocated_bytes <- (# peek GCDetails, allocated_bytes) pgc
184       gcdetails_live_bytes <- (# peek GCDetails, live_bytes) pgc
185       gcdetails_large_objects_bytes <-
186         (# peek GCDetails, large_objects_bytes) pgc
187       gcdetails_compact_bytes <- (# peek GCDetails, compact_bytes) pgc
188       gcdetails_slop_bytes <- (# peek GCDetails, slop_bytes) pgc
189       gcdetails_mem_in_use_bytes <- (# peek GCDetails, mem_in_use_bytes) pgc
190       gcdetails_copied_bytes <- (# peek GCDetails, copied_bytes) pgc
191       gcdetails_par_max_copied_bytes <-
192         (# peek GCDetails, par_max_copied_bytes) pgc
193       gcdetails_sync_elapsed_ns <- (# peek GCDetails, sync_elapsed_ns) pgc
194       gcdetails_cpu_ns <- (# peek GCDetails, cpu_ns) pgc
195       gcdetails_elapsed_ns <- (# peek GCDetails, elapsed_ns) pgc
196       return GCDetails{..}
197     return RTSStats{..}
198
199 -- -----------------------------------------------------------------------------
200 -- DEPRECATED API
201
202 -- I'm probably violating a bucket of constraints here... oops.
203
204 -- | Statistics about memory usage and the garbage collector. Apart from
205 -- 'currentBytesUsed' and 'currentBytesSlop' all are cumulative values since
206 -- the program started.
207 --
208 -- @since 4.5.0.0
209 {-# DEPRECATED GCStats "Use RTSStats instead.  This will be removed in GHC 8.4.1" #-}
210 data GCStats = GCStats
211     { -- | Total number of bytes allocated
212     bytesAllocated :: !Int64
213     -- | Number of garbage collections performed (any generation, major and
214     -- minor)
215     , numGcs :: !Int64
216     -- | Maximum number of live bytes seen so far
217     , maxBytesUsed :: !Int64
218     -- | Number of byte usage samples taken, or equivalently
219     -- the number of major GCs performed.
220     , numByteUsageSamples :: !Int64
221     -- | Sum of all byte usage samples, can be used with
222     -- 'numByteUsageSamples' to calculate averages with
223     -- arbitrary weighting (if you are sampling this record multiple
224     -- times).
225     , cumulativeBytesUsed :: !Int64
226     -- | Number of bytes copied during GC
227     , bytesCopied :: !Int64
228     -- | Number of live bytes at the end of the last major GC
229     , currentBytesUsed :: !Int64
230     -- | Current number of bytes lost to slop
231     , currentBytesSlop :: !Int64
232     -- | Maximum number of bytes lost to slop at any one time so far
233     , maxBytesSlop :: !Int64
234     -- | Maximum number of megabytes allocated
235     , peakMegabytesAllocated :: !Int64
236     -- | CPU time spent running mutator threads.  This does not include
237     -- any profiling overhead or initialization.
238     , mblocksAllocated :: !Int64 -- ^ Number of allocated megablocks
239     , mutatorCpuSeconds :: !Double
240
241     -- | Wall clock time spent running mutator threads.  This does not
242     -- include initialization.
243     , mutatorWallSeconds :: !Double
244     -- | CPU time spent running GC
245     , gcCpuSeconds :: !Double
246     -- | Wall clock time spent running GC
247     , gcWallSeconds :: !Double
248     -- | Total CPU time elapsed since program start
249     , cpuSeconds :: !Double
250     -- | Total wall clock time elapsed since start
251     , wallSeconds :: !Double
252     -- | Number of bytes copied during GC, minus space held by mutable
253     -- lists held by the capabilities.  Can be used with
254     -- 'parMaxBytesCopied' to determine how well parallel GC utilized
255     -- all cores.
256     , parTotBytesCopied :: !Int64
257
258     -- | Sum of number of bytes copied each GC by the most active GC
259     -- thread each GC.  The ratio of 'parTotBytesCopied' divided by
260     -- 'parMaxBytesCopied' approaches 1 for a maximally sequential
261     -- run and approaches the number of threads (set by the RTS flag
262     -- @-N@) for a maximally parallel run.
263     , parMaxBytesCopied :: !Int64
264     } deriving (Show, Read)
265
266 -- | Retrieves garbage collection and memory statistics as of the last
267 -- garbage collection.  If you would like your statistics as recent as
268 -- possible, first run a 'System.Mem.performGC'.
269 --
270 -- @since 4.5.0.0
271 {-# DEPRECATED getGCStats
272     "Use getRTSStats instead.  This will be removed in GHC 8.4.1" #-}
273 getGCStats :: IO GCStats
274 getGCStats = do
275   statsEnabled <- getGCStatsEnabled
276   unless statsEnabled .  ioError $ IOError
277     Nothing
278     UnsupportedOperation
279     ""
280     "getGCStats: GC stats not enabled. Use `+RTS -T -RTS' to enable them."
281     Nothing
282     Nothing
283   allocaBytes (#size RTSStats) $ \p -> do
284     getRTSStats_ p
285     bytesAllocated <- (# peek RTSStats, allocated_bytes) p
286     numGcs <- (# peek RTSStats, gcs ) p
287     numByteUsageSamples <- (# peek RTSStats, major_gcs ) p
288     maxBytesUsed <- (# peek RTSStats, max_live_bytes ) p
289     cumulativeBytesUsed <- (# peek RTSStats, cumulative_live_bytes ) p
290     bytesCopied <- (# peek RTSStats, copied_bytes ) p
291     currentBytesUsed <- (# peek RTSStats, gc.live_bytes ) p
292     currentBytesSlop <- (# peek RTSStats, gc.slop_bytes) p
293     maxBytesSlop <- (# peek RTSStats, max_slop_bytes) p
294     peakMegabytesAllocated <- do
295       bytes <- (# peek RTSStats, max_mem_in_use_bytes ) p
296       return (bytes `quot` (1024*1024))
297     mblocksAllocated <- do
298       bytes <- (# peek RTSStats, gc.mem_in_use_bytes) p
299       return (bytes `quot` (1024*1024))
300     mutatorCpuSeconds <- nsToSecs <$> (# peek RTSStats, mutator_cpu_ns) p
301     mutatorWallSeconds <-
302       nsToSecs <$> (# peek RTSStats, mutator_elapsed_ns) p
303     gcCpuSeconds <- nsToSecs <$> (# peek RTSStats, gc_cpu_ns) p
304     gcWallSeconds <- nsToSecs <$> (# peek RTSStats, gc_elapsed_ns) p
305     cpuSeconds <- nsToSecs <$> (# peek RTSStats, cpu_ns) p
306     wallSeconds <- nsToSecs <$> (# peek RTSStats, elapsed_ns) p
307     parTotBytesCopied <- (# peek RTSStats, par_copied_bytes) p
308     parMaxBytesCopied <- (# peek RTSStats, cumulative_par_max_copied_bytes) p
309     return GCStats { .. }
310
311 nsToSecs :: Int64 -> Double
312 nsToSecs ns = fromIntegral ns / (# const TIME_RESOLUTION)
313
314 {-# DEPRECATED getGCStatsEnabled
315     "use getRTSStatsEnabled instead.  This will be removed in GHC 8.4.1" #-}
316 getGCStatsEnabled :: IO Bool
317 getGCStatsEnabled = getRTSStatsEnabled