Compact Regions
[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 // Specify the Capability that the current OS thread should run on when it calls
176 // into Haskell. The actual capability will be calculated as the supplied
177 // value modulo the number of enabled Capabilities.
178 //
179 // Note that the thread may still be migrated by the RTS scheduler, but that
180 // will only happen if there are multiple threads running on one Capability and
181 // another Capability is free.
182 //
183 // If affinity is non-zero, the current thread will be bound to
184 // specific CPUs according to the prevailing affinity policy for the
185 // specified capability, set by either +RTS -qa or +RTS --numa.
186 void rts_setInCallCapability (int preferred_capability, int affinity);
187
188 /* ----------------------------------------------------------------------------
189 Building Haskell objects from C datatypes.
190 ------------------------------------------------------------------------- */
191 HaskellObj rts_mkChar ( Capability *, HsChar c );
192 HaskellObj rts_mkInt ( Capability *, HsInt i );
193 HaskellObj rts_mkInt8 ( Capability *, HsInt8 i );
194 HaskellObj rts_mkInt16 ( Capability *, HsInt16 i );
195 HaskellObj rts_mkInt32 ( Capability *, HsInt32 i );
196 HaskellObj rts_mkInt64 ( Capability *, HsInt64 i );
197 HaskellObj rts_mkWord ( Capability *, HsWord w );
198 HaskellObj rts_mkWord8 ( Capability *, HsWord8 w );
199 HaskellObj rts_mkWord16 ( Capability *, HsWord16 w );
200 HaskellObj rts_mkWord32 ( Capability *, HsWord32 w );
201 HaskellObj rts_mkWord64 ( Capability *, HsWord64 w );
202 HaskellObj rts_mkPtr ( Capability *, HsPtr a );
203 HaskellObj rts_mkFunPtr ( Capability *, HsFunPtr a );
204 HaskellObj rts_mkFloat ( Capability *, HsFloat f );
205 HaskellObj rts_mkDouble ( Capability *, HsDouble f );
206 HaskellObj rts_mkStablePtr ( Capability *, HsStablePtr s );
207 HaskellObj rts_mkBool ( Capability *, HsBool b );
208 HaskellObj rts_mkString ( Capability *, char *s );
209
210 HaskellObj rts_apply ( Capability *, HaskellObj, HaskellObj );
211
212 /* ----------------------------------------------------------------------------
213 Deconstructing Haskell objects
214 ------------------------------------------------------------------------- */
215 HsChar rts_getChar ( HaskellObj );
216 HsInt rts_getInt ( HaskellObj );
217 HsInt8 rts_getInt8 ( HaskellObj );
218 HsInt16 rts_getInt16 ( HaskellObj );
219 HsInt32 rts_getInt32 ( HaskellObj );
220 HsInt64 rts_getInt64 ( HaskellObj );
221 HsWord rts_getWord ( HaskellObj );
222 HsWord8 rts_getWord8 ( HaskellObj );
223 HsWord16 rts_getWord16 ( HaskellObj );
224 HsWord32 rts_getWord32 ( HaskellObj );
225 HsWord64 rts_getWord64 ( HaskellObj );
226 HsPtr rts_getPtr ( HaskellObj );
227 HsFunPtr rts_getFunPtr ( HaskellObj );
228 HsFloat rts_getFloat ( HaskellObj );
229 HsDouble rts_getDouble ( HaskellObj );
230 HsStablePtr rts_getStablePtr ( HaskellObj );
231 HsBool rts_getBool ( HaskellObj );
232
233 /* ----------------------------------------------------------------------------
234 Evaluating Haskell expressions
235
236 The versions ending in '_' allow you to specify an initial stack size.
237 Note that these calls may cause Garbage Collection, so all HaskellObj
238 references are rendered invalid by these calls.
239
240 All of these functions take a (Capability **) - there is a
241 Capability pointer both input and output. We use an inout
242 parameter because this is less error-prone for the client than a
243 return value - the client could easily forget to use the return
244 value, whereas incorrectly using an inout parameter will usually
245 result in a type error.
246 ------------------------------------------------------------------------- */
247
248 void rts_eval (/* inout */ Capability **,
249 /* in */ HaskellObj p,
250 /* out */ HaskellObj *ret);
251
252 void rts_eval_ (/* inout */ Capability **,
253 /* in */ HaskellObj p,
254 /* in */ unsigned int stack_size,
255 /* out */ HaskellObj *ret);
256
257 void rts_evalIO (/* inout */ Capability **,
258 /* in */ HaskellObj p,
259 /* out */ HaskellObj *ret);
260
261 void rts_evalStableIO (/* inout */ Capability **,
262 /* in */ HsStablePtr s,
263 /* out */ HsStablePtr *ret);
264
265 void rts_evalLazyIO (/* inout */ Capability **,
266 /* in */ HaskellObj p,
267 /* out */ HaskellObj *ret);
268
269 void rts_evalLazyIO_ (/* inout */ Capability **,
270 /* in */ HaskellObj p,
271 /* in */ unsigned int stack_size,
272 /* out */ HaskellObj *ret);
273
274 void rts_checkSchedStatus (char* site, Capability *);
275
276 SchedulerStatus rts_getSchedStatus (Capability *cap);
277
278 /*
279 * The RTS allocates some thread-local data when you make a call into
280 * Haskell using one of the rts_eval() functions. This data is not
281 * normally freed until hs_exit(). If you want to free it earlier
282 * than this, perhaps because the thread is about to exit, then call
283 * rts_done() from the thread.
284 *
285 * It is safe to make more rts_eval() calls after calling rts_done(),
286 * but the next one will cause allocation of the thread-local memory
287 * again.
288 */
289 void rts_done (void);
290
291 /* --------------------------------------------------------------------------
292 Wrapper closures
293
294 These are used by foreign export and foreign import "wrapper" stubs.
295 ----------------------------------------------------------------------- */
296
297 // When producing Windows DLLs the we need to know which symbols are in the
298 // local package/DLL vs external ones.
299 //
300 // Note that RtsAPI.h is also included by foreign export stubs in
301 // the base package itself.
302 //
303 #if defined(COMPILING_WINDOWS_DLL) && !defined(COMPILING_BASE_PACKAGE)
304 __declspec(dllimport) extern StgWord base_GHCziTopHandler_runIO_closure[];
305 __declspec(dllimport) extern StgWord base_GHCziTopHandler_runNonIO_closure[];
306 #else
307 extern StgWord base_GHCziTopHandler_runIO_closure[];
308 extern StgWord base_GHCziTopHandler_runNonIO_closure[];
309 #endif
310
311 #define runIO_closure base_GHCziTopHandler_runIO_closure
312 #define runNonIO_closure base_GHCziTopHandler_runNonIO_closure
313
314 /* ------------------------------------------------------------------------ */
315
316 #ifdef __cplusplus
317 }
318 #endif
319
320 #endif /* RTSAPI_H */