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