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