Fix Work Balance computation in RTS stats
[ghc.git] / includes / RtsAPI.h
1 /* ----------------------------------------------------------------------------
2 *
3 * (c) The GHC Team, 1998-2004
4 *
5 * API for invoking Haskell functions via the RTS
6 *
7 * To understand the structure of the RTS headers, see the wiki:
8 * http://ghc.haskell.org/trac/ghc/wiki/Commentary/SourceTree/Includes
9 *
10 * --------------------------------------------------------------------------*/
11
12 #pragma once
13
14 #if defined(__cplusplus)
15 extern "C" {
16 #endif
17
18 #include "HsFFI.h"
19 #include "rts/Time.h"
20 #include "rts/EventLogWriter.h"
21
22 /*
23 * Running the scheduler
24 */
25 typedef enum {
26 NoStatus, /* not finished yet */
27 Success, /* completed successfully */
28 Killed, /* uncaught exception */
29 Interrupted, /* stopped in response to a call to interruptStgRts */
30 HeapExhausted /* out of memory */
31 } SchedulerStatus;
32
33 typedef struct StgClosure_ *HaskellObj;
34
35 /*
36 * An abstract type representing the token returned by rts_lock() and
37 * used when allocating objects and threads in the RTS.
38 */
39 typedef struct Capability_ Capability;
40
41 /*
42 * The public view of a Capability: we can be sure it starts with
43 * these two components (but it may have more private fields).
44 */
45 typedef struct CapabilityPublic_ {
46 StgFunTable f;
47 StgRegTable r;
48 } CapabilityPublic;
49
50 /* ----------------------------------------------------------------------------
51 RTS configuration settings, for passing to hs_init_ghc()
52 ------------------------------------------------------------------------- */
53
54 typedef enum {
55 RtsOptsNone, // +RTS causes an error
56 RtsOptsSafeOnly, // safe RTS options allowed; others cause an error
57 RtsOptsAll // all RTS options allowed
58 } RtsOptsEnabledEnum;
59
60 struct GCDetails_;
61
62 // The RtsConfig struct is passed (by value) to hs_init_ghc(). The
63 // reason for using a struct is extensibility: we can add more
64 // fields to this later without breaking existing client code.
65 typedef struct {
66
67 // Whether to interpret +RTS options on the command line
68 RtsOptsEnabledEnum rts_opts_enabled;
69
70 // Whether to give RTS flag suggestions
71 HsBool rts_opts_suggestions;
72
73 // additional RTS options
74 const char *rts_opts;
75
76 // True if GHC was not passed -no-hs-main
77 HsBool rts_hs_main;
78
79 // Whether to retain CAFs (default: false)
80 HsBool keep_cafs;
81
82 // Writer a for eventlog.
83 const EventLogWriter *eventlog_writer;
84
85 // Called before processing command-line flags, so that default
86 // settings for RtsFlags can be provided.
87 void (* defaultsHook) (void);
88
89 // Called just before exiting
90 void (* onExitHook) (void);
91
92 // Called on a stack overflow, before exiting
93 void (* stackOverflowHook) (W_ stack_size);
94
95 // Called on heap overflow, before exiting
96 void (* outOfHeapHook) (W_ request_size, W_ heap_size);
97
98 // Called when malloc() fails, before exiting
99 void (* mallocFailHook) (W_ request_size /* in bytes */, const char *msg);
100
101 // Called for every GC
102 void (* gcDoneHook) (const struct GCDetails_ *stats);
103 } RtsConfig;
104
105 // Clients should start with defaultRtsConfig and then customise it.
106 // Bah, I really wanted this to be a const struct value, but it seems
107 // you can't do that in C (it generates code).
108 extern const RtsConfig defaultRtsConfig;
109
110 /* -----------------------------------------------------------------------------
111 Statistics
112 -------------------------------------------------------------------------- */
113
114 //
115 // Stats about a single GC
116 //
117 typedef struct GCDetails_ {
118 // The generation number of this GC
119 uint32_t gen;
120 // Number of threads used in this GC
121 uint32_t threads;
122 // Number of bytes allocated since the previous GC
123 uint64_t allocated_bytes;
124 // Total amount of live data in the heap (incliudes large + compact data)
125 uint64_t live_bytes;
126 // Total amount of live data in large objects
127 uint64_t large_objects_bytes;
128 // Total amount of live data in compact regions
129 uint64_t compact_bytes;
130 // Total amount of slop (wasted memory)
131 uint64_t slop_bytes;
132 // Total amount of memory in use by the RTS
133 uint64_t mem_in_use_bytes;
134 // Total amount of data copied during this GC
135 uint64_t copied_bytes;
136 // In parallel GC, the max amount of data copied by any one thread
137 uint64_t par_max_copied_bytes;
138 // In parallel GC, the amount of balanced data copied by all threads
139 uint64_t par_balanced_copied_bytes;
140 // The time elapsed during synchronisation before GC
141 Time sync_elapsed_ns;
142 // The CPU time used during GC itself
143 Time cpu_ns;
144 // The time elapsed during GC itself
145 Time elapsed_ns;
146 } GCDetails;
147
148 //
149 // Stats about the RTS currently, and since the start of execution
150 //
151 typedef struct _RTSStats {
152
153 // -----------------------------------
154 // Cumulative stats about memory use
155
156 // Total number of GCs
157 uint32_t gcs;
158 // Total number of major (oldest generation) GCs
159 uint32_t major_gcs;
160 // Total bytes allocated
161 uint64_t allocated_bytes;
162 // Maximum live data (including large objects + compact regions)
163 uint64_t max_live_bytes;
164 // Maximum live data in large objects
165 uint64_t max_large_objects_bytes;
166 // Maximum live data in compact regions
167 uint64_t max_compact_bytes;
168 // Maximum slop
169 uint64_t max_slop_bytes;
170 // Maximum memory in use by the RTS
171 uint64_t max_mem_in_use_bytes;
172 // Sum of live bytes across all major GCs. Divided by major_gcs
173 // gives the average live data over the lifetime of the program.
174 uint64_t cumulative_live_bytes;
175 // Sum of copied_bytes across all GCs
176 uint64_t copied_bytes;
177 // Sum of copied_bytes across all parallel GCs
178 uint64_t par_copied_bytes;
179 // Sum of par_max_copied_bytes across all parallel GCs
180 uint64_t cumulative_par_max_copied_bytes;
181 // Sum of par_balanced_copied_byes across all parallel GCs.
182 uint64_t cumulative_par_balanced_copied_bytes;
183
184 // -----------------------------------
185 // Cumulative stats about time use
186 // (we use signed values here because due to inaccuracies in timers
187 // the values can occasionally go slightly negative)
188
189 // Total CPU time used by the mutator
190 Time mutator_cpu_ns;
191 // Total elapsed time used by the mutator
192 Time mutator_elapsed_ns;
193 // Total CPU time used by the GC
194 Time gc_cpu_ns;
195 // Total elapsed time used by the GC
196 Time gc_elapsed_ns;
197 // Total CPU time (at the previous GC)
198 Time cpu_ns;
199 // Total elapsed time (at the previous GC)
200 Time elapsed_ns;
201
202 // -----------------------------------
203 // Stats about the most recent GC
204
205 GCDetails gc;
206
207 } RTSStats;
208
209 void getRTSStats (RTSStats *s);
210 int getRTSStatsEnabled (void);
211
212 // Returns the total number of bytes allocated since the start of the program.
213 // TODO: can we remove this?
214 uint64_t getAllocations (void);
215
216 /* ----------------------------------------------------------------------------
217 Starting up and shutting down the Haskell RTS.
218 ------------------------------------------------------------------------- */
219
220 /* DEPRECATED, use hs_init() or hs_init_ghc() instead */
221 extern void startupHaskell ( int argc, char *argv[],
222 void (*init_root)(void) );
223
224 /* DEPRECATED, use hs_exit() instead */
225 extern void shutdownHaskell ( void );
226
227 /* Like hs_init(), but allows rtsopts. For more complicated usage,
228 * use hs_init_ghc. */
229 extern void hs_init_with_rtsopts (int *argc, char **argv[]);
230
231 /*
232 * GHC-specific version of hs_init() that allows specifying whether
233 * +RTS ... -RTS options are allowed or not (default: only "safe"
234 * options are allowed), and allows passing an option string that is
235 * to be interpreted by the RTS only, not passed to the program.
236 */
237 extern void hs_init_ghc (int *argc, char **argv[], // program arguments
238 RtsConfig rts_config); // RTS configuration
239
240 extern void shutdownHaskellAndExit (int exitCode, int fastExit)
241 GNUC3_ATTRIBUTE(__noreturn__);
242
243 #if !defined(mingw32_HOST_OS)
244 extern void shutdownHaskellAndSignal (int sig, int fastExit)
245 GNUC3_ATTRIBUTE(__noreturn__);
246 #endif
247
248 extern void getProgArgv ( int *argc, char **argv[] );
249 extern void setProgArgv ( int argc, char *argv[] );
250 extern void getFullProgArgv ( int *argc, char **argv[] );
251 extern void setFullProgArgv ( int argc, char *argv[] );
252 extern void freeFullProgArgv ( void ) ;
253
254 /* exit() override */
255 extern void (*exitFn)(int);
256
257 /* ----------------------------------------------------------------------------
258 Locking.
259
260 You have to surround all access to the RtsAPI with these calls.
261 ------------------------------------------------------------------------- */
262
263 // acquires a token which may be used to create new objects and
264 // evaluate them.
265 Capability *rts_lock (void);
266
267 // releases the token acquired with rts_lock().
268 void rts_unlock (Capability *token);
269
270 // If you are in a context where you know you have a current capability but
271 // do not know what it is, then use this to get it. Basically this only
272 // applies to "unsafe" foreign calls (as unsafe foreign calls are made with
273 // the capability held).
274 //
275 // WARNING: There is *no* guarantee this returns anything sensible (eg NULL)
276 // when there is no current capability.
277 Capability *rts_unsafeGetMyCapability (void);
278
279 /* ----------------------------------------------------------------------------
280 Which cpu should the OS thread and Haskell thread run on?
281
282 1. Run the current thread on the given capability:
283 rts_setInCallCapability(cap, 0);
284
285 2. Run the current thread on the given capability and set the cpu affinity
286 for this thread:
287 rts_setInCallCapability(cap, 1);
288
289 3. Run the current thread on the given numa node:
290 rts_pinThreadToNumaNode(node);
291
292 4. Run the current thread on the given capability and on the given numa node:
293 rts_setInCallCapability(cap, 0);
294 rts_pinThreadToNumaNode(cap);
295 ------------------------------------------------------------------------- */
296
297 // Specify the Capability that the current OS thread should run on when it calls
298 // into Haskell. The actual capability will be calculated as the supplied
299 // value modulo the number of enabled Capabilities.
300 //
301 // Note that the thread may still be migrated by the RTS scheduler, but that
302 // will only happen if there are multiple threads running on one Capability and
303 // another Capability is free.
304 //
305 // If affinity is non-zero, the current thread will be bound to
306 // specific CPUs according to the prevailing affinity policy for the
307 // specified capability, set by either +RTS -qa or +RTS --numa.
308 void rts_setInCallCapability (int preferred_capability, int affinity);
309
310 // Specify the CPU Node that the current OS thread should run on when it calls
311 // into Haskell. The argument can be either a node number or capability number.
312 // The actual node will be calculated as the supplied value modulo the number
313 // of numa nodes.
314 void rts_pinThreadToNumaNode (int node);
315
316 /* ----------------------------------------------------------------------------
317 Building Haskell objects from C datatypes.
318 ------------------------------------------------------------------------- */
319 HaskellObj rts_mkChar ( Capability *, HsChar c );
320 HaskellObj rts_mkInt ( Capability *, HsInt i );
321 HaskellObj rts_mkInt8 ( Capability *, HsInt8 i );
322 HaskellObj rts_mkInt16 ( Capability *, HsInt16 i );
323 HaskellObj rts_mkInt32 ( Capability *, HsInt32 i );
324 HaskellObj rts_mkInt64 ( Capability *, HsInt64 i );
325 HaskellObj rts_mkWord ( Capability *, HsWord w );
326 HaskellObj rts_mkWord8 ( Capability *, HsWord8 w );
327 HaskellObj rts_mkWord16 ( Capability *, HsWord16 w );
328 HaskellObj rts_mkWord32 ( Capability *, HsWord32 w );
329 HaskellObj rts_mkWord64 ( Capability *, HsWord64 w );
330 HaskellObj rts_mkPtr ( Capability *, HsPtr a );
331 HaskellObj rts_mkFunPtr ( Capability *, HsFunPtr a );
332 HaskellObj rts_mkFloat ( Capability *, HsFloat f );
333 HaskellObj rts_mkDouble ( Capability *, HsDouble f );
334 HaskellObj rts_mkStablePtr ( Capability *, HsStablePtr s );
335 HaskellObj rts_mkBool ( Capability *, HsBool b );
336 HaskellObj rts_mkString ( Capability *, char *s );
337
338 HaskellObj rts_apply ( Capability *, HaskellObj, HaskellObj );
339
340 /* ----------------------------------------------------------------------------
341 Deconstructing Haskell objects
342 ------------------------------------------------------------------------- */
343 HsChar rts_getChar ( HaskellObj );
344 HsInt rts_getInt ( HaskellObj );
345 HsInt8 rts_getInt8 ( HaskellObj );
346 HsInt16 rts_getInt16 ( HaskellObj );
347 HsInt32 rts_getInt32 ( HaskellObj );
348 HsInt64 rts_getInt64 ( HaskellObj );
349 HsWord rts_getWord ( HaskellObj );
350 HsWord8 rts_getWord8 ( HaskellObj );
351 HsWord16 rts_getWord16 ( HaskellObj );
352 HsWord32 rts_getWord32 ( HaskellObj );
353 HsWord64 rts_getWord64 ( HaskellObj );
354 HsPtr rts_getPtr ( HaskellObj );
355 HsFunPtr rts_getFunPtr ( HaskellObj );
356 HsFloat rts_getFloat ( HaskellObj );
357 HsDouble rts_getDouble ( HaskellObj );
358 HsStablePtr rts_getStablePtr ( HaskellObj );
359 HsBool rts_getBool ( HaskellObj );
360
361 /* ----------------------------------------------------------------------------
362 Evaluating Haskell expressions
363
364 The versions ending in '_' allow you to specify an initial stack size.
365 Note that these calls may cause Garbage Collection, so all HaskellObj
366 references are rendered invalid by these calls.
367
368 All of these functions take a (Capability **) - there is a
369 Capability pointer both input and output. We use an inout
370 parameter because this is less error-prone for the client than a
371 return value - the client could easily forget to use the return
372 value, whereas incorrectly using an inout parameter will usually
373 result in a type error.
374 ------------------------------------------------------------------------- */
375
376 void rts_eval (/* inout */ Capability **,
377 /* in */ HaskellObj p,
378 /* out */ HaskellObj *ret);
379
380 void rts_eval_ (/* inout */ Capability **,
381 /* in */ HaskellObj p,
382 /* in */ unsigned int stack_size,
383 /* out */ HaskellObj *ret);
384
385 void rts_evalIO (/* inout */ Capability **,
386 /* in */ HaskellObj p,
387 /* out */ HaskellObj *ret);
388
389 void rts_evalStableIOMain (/* inout */ Capability **,
390 /* in */ HsStablePtr s,
391 /* out */ HsStablePtr *ret);
392
393 void rts_evalStableIO (/* inout */ Capability **,
394 /* in */ HsStablePtr s,
395 /* out */ HsStablePtr *ret);
396
397 void rts_evalLazyIO (/* inout */ Capability **,
398 /* in */ HaskellObj p,
399 /* out */ HaskellObj *ret);
400
401 void rts_evalLazyIO_ (/* inout */ Capability **,
402 /* in */ HaskellObj p,
403 /* in */ unsigned int stack_size,
404 /* out */ HaskellObj *ret);
405
406 void rts_checkSchedStatus (char* site, Capability *);
407
408 SchedulerStatus rts_getSchedStatus (Capability *cap);
409
410 /*
411 * The RTS allocates some thread-local data when you make a call into
412 * Haskell using one of the rts_eval() functions. This data is not
413 * normally freed until hs_exit(). If you want to free it earlier
414 * than this, perhaps because the thread is about to exit, then call
415 * rts_done() from the thread.
416 *
417 * It is safe to make more rts_eval() calls after calling rts_done(),
418 * but the next one will cause allocation of the thread-local memory
419 * again.
420 */
421 void rts_done (void);
422
423 /* --------------------------------------------------------------------------
424 Wrapper closures
425
426 These are used by foreign export and foreign import "wrapper" stubs.
427 ----------------------------------------------------------------------- */
428
429 // When producing Windows DLLs the we need to know which symbols are in the
430 // local package/DLL vs external ones.
431 //
432 // Note that RtsAPI.h is also included by foreign export stubs in
433 // the base package itself.
434 //
435 #if defined(COMPILING_WINDOWS_DLL) && !defined(COMPILING_BASE_PACKAGE)
436 __declspec(dllimport) extern StgWord base_GHCziTopHandler_runIO_closure[];
437 __declspec(dllimport) extern StgWord base_GHCziTopHandler_runNonIO_closure[];
438 #else
439 extern StgWord base_GHCziTopHandler_runIO_closure[];
440 extern StgWord base_GHCziTopHandler_runNonIO_closure[];
441 #endif
442
443 #define runIO_closure base_GHCziTopHandler_runIO_closure
444 #define runNonIO_closure base_GHCziTopHandler_runNonIO_closure
445
446 /* ------------------------------------------------------------------------ */
447
448 #if defined(__cplusplus)
449 }
450 #endif