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