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