rts: add "-no-rtsopts-suggestions" option
[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 // Called before processing command-line flags, so that default
77 // settings for RtsFlags can be provided.
78 void (* defaultsHook) (void);
79
80 // Called just before exiting
81 void (* onExitHook) (void);
82
83 // Called on a stack overflow, before exiting
84 void (* stackOverflowHook) (W_ stack_size);
85
86 // Called on heap overflow, before exiting
87 void (* outOfHeapHook) (W_ request_size, W_ heap_size);
88
89 // Called when malloc() fails, before exiting
90 void (* mallocFailHook) (W_ request_size /* in bytes */, char *msg);
91
92 // Called for every GC
93 void (* gcDoneHook) (unsigned int gen,
94 W_ allocated_bytes, /* since last GC */
95 W_ live_bytes,
96 W_ copied_bytes,
97 W_ max_copied_per_thread_bytes,
98 W_ total_bytes,
99 W_ slop_bytes,
100 W_ sync_elapsed_ns, W_ elapsed_ns, W_ cpu_ns);
101
102 } RtsConfig;
103
104 // Clients should start with defaultRtsConfig and then customise it.
105 // Bah, I really wanted this to be a const struct value, but it seems
106 // you can't do that in C (it generates code).
107 extern const RtsConfig defaultRtsConfig;
108
109 /* ----------------------------------------------------------------------------
110 Starting up and shutting down the Haskell RTS.
111 ------------------------------------------------------------------------- */
112
113 /* DEPRECATED, use hs_init() or hs_init_ghc() instead */
114 extern void startupHaskell ( int argc, char *argv[],
115 void (*init_root)(void) );
116
117 /* DEPRECATED, use hs_exit() instead */
118 extern void shutdownHaskell ( void );
119
120 /* Like hs_init(), but allows rtsopts. For more complicated usage,
121 * use hs_init_ghc. */
122 extern void hs_init_with_rtsopts (int *argc, char **argv[]);
123
124 /*
125 * GHC-specific version of hs_init() that allows specifying whether
126 * +RTS ... -RTS options are allowed or not (default: only "safe"
127 * options are allowed), and allows passing an option string that is
128 * to be interpreted by the RTS only, not passed to the program.
129 */
130 extern void hs_init_ghc (int *argc, char **argv[], // program arguments
131 RtsConfig rts_config); // RTS configuration
132
133 extern void shutdownHaskellAndExit (int exitCode, int fastExit)
134 GNUC3_ATTRIBUTE(__noreturn__);
135
136 #ifndef mingw32_HOST_OS
137 extern void shutdownHaskellAndSignal (int sig, int fastExit)
138 GNUC3_ATTRIBUTE(__noreturn__);
139 #endif
140
141 extern void getProgArgv ( int *argc, char **argv[] );
142 extern void setProgArgv ( int argc, char *argv[] );
143 extern void getFullProgArgv ( int *argc, char **argv[] );
144 extern void setFullProgArgv ( int argc, char *argv[] );
145 extern void freeFullProgArgv ( void ) ;
146
147 /* exit() override */
148 extern void (*exitFn)(int);
149
150 /* ----------------------------------------------------------------------------
151 Locking.
152
153 You have to surround all access to the RtsAPI with these calls.
154 ------------------------------------------------------------------------- */
155
156 // acquires a token which may be used to create new objects and
157 // evaluate them.
158 Capability *rts_lock (void);
159
160 // releases the token acquired with rts_lock().
161 void rts_unlock (Capability *token);
162
163 // If you are in a context where you know you have a current capability but
164 // do not know what it is, then use this to get it. Basically this only
165 // applies to "unsafe" foreign calls (as unsafe foreign calls are made with
166 // the capability held).
167 //
168 // WARNING: There is *no* guarantee this returns anything sensible (eg NULL)
169 // when there is no current capability.
170 Capability *rts_unsafeGetMyCapability (void);
171
172 /* ----------------------------------------------------------------------------
173 Building Haskell objects from C datatypes.
174 ------------------------------------------------------------------------- */
175 HaskellObj rts_mkChar ( Capability *, HsChar c );
176 HaskellObj rts_mkInt ( Capability *, HsInt i );
177 HaskellObj rts_mkInt8 ( Capability *, HsInt8 i );
178 HaskellObj rts_mkInt16 ( Capability *, HsInt16 i );
179 HaskellObj rts_mkInt32 ( Capability *, HsInt32 i );
180 HaskellObj rts_mkInt64 ( Capability *, HsInt64 i );
181 HaskellObj rts_mkWord ( Capability *, HsWord w );
182 HaskellObj rts_mkWord8 ( Capability *, HsWord8 w );
183 HaskellObj rts_mkWord16 ( Capability *, HsWord16 w );
184 HaskellObj rts_mkWord32 ( Capability *, HsWord32 w );
185 HaskellObj rts_mkWord64 ( Capability *, HsWord64 w );
186 HaskellObj rts_mkPtr ( Capability *, HsPtr a );
187 HaskellObj rts_mkFunPtr ( Capability *, HsFunPtr a );
188 HaskellObj rts_mkFloat ( Capability *, HsFloat f );
189 HaskellObj rts_mkDouble ( Capability *, HsDouble f );
190 HaskellObj rts_mkStablePtr ( Capability *, HsStablePtr s );
191 HaskellObj rts_mkBool ( Capability *, HsBool b );
192 HaskellObj rts_mkString ( Capability *, char *s );
193
194 HaskellObj rts_apply ( Capability *, HaskellObj, HaskellObj );
195
196 /* ----------------------------------------------------------------------------
197 Deconstructing Haskell objects
198 ------------------------------------------------------------------------- */
199 HsChar rts_getChar ( HaskellObj );
200 HsInt rts_getInt ( HaskellObj );
201 HsInt8 rts_getInt8 ( HaskellObj );
202 HsInt16 rts_getInt16 ( HaskellObj );
203 HsInt32 rts_getInt32 ( HaskellObj );
204 HsInt64 rts_getInt64 ( HaskellObj );
205 HsWord rts_getWord ( HaskellObj );
206 HsWord8 rts_getWord8 ( HaskellObj );
207 HsWord16 rts_getWord16 ( HaskellObj );
208 HsWord32 rts_getWord32 ( HaskellObj );
209 HsWord64 rts_getWord64 ( HaskellObj );
210 HsPtr rts_getPtr ( HaskellObj );
211 HsFunPtr rts_getFunPtr ( HaskellObj );
212 HsFloat rts_getFloat ( HaskellObj );
213 HsDouble rts_getDouble ( HaskellObj );
214 HsStablePtr rts_getStablePtr ( HaskellObj );
215 HsBool rts_getBool ( HaskellObj );
216
217 /* ----------------------------------------------------------------------------
218 Evaluating Haskell expressions
219
220 The versions ending in '_' allow you to specify an initial stack size.
221 Note that these calls may cause Garbage Collection, so all HaskellObj
222 references are rendered invalid by these calls.
223
224 All of these functions take a (Capability **) - there is a
225 Capability pointer both input and output. We use an inout
226 parameter because this is less error-prone for the client than a
227 return value - the client could easily forget to use the return
228 value, whereas incorrectly using an inout parameter will usually
229 result in a type error.
230 ------------------------------------------------------------------------- */
231
232 void rts_eval (/* inout */ Capability **,
233 /* in */ HaskellObj p,
234 /* out */ HaskellObj *ret);
235
236 void rts_eval_ (/* inout */ Capability **,
237 /* in */ HaskellObj p,
238 /* in */ unsigned int stack_size,
239 /* out */ HaskellObj *ret);
240
241 void rts_evalIO (/* inout */ Capability **,
242 /* in */ HaskellObj p,
243 /* out */ HaskellObj *ret);
244
245 void rts_evalStableIO (/* inout */ Capability **,
246 /* in */ HsStablePtr s,
247 /* out */ HsStablePtr *ret);
248
249 void rts_evalLazyIO (/* inout */ Capability **,
250 /* in */ HaskellObj p,
251 /* out */ HaskellObj *ret);
252
253 void rts_evalLazyIO_ (/* inout */ Capability **,
254 /* in */ HaskellObj p,
255 /* in */ unsigned int stack_size,
256 /* out */ HaskellObj *ret);
257
258 void rts_checkSchedStatus (char* site, Capability *);
259
260 SchedulerStatus rts_getSchedStatus (Capability *cap);
261
262 /*
263 * The RTS allocates some thread-local data when you make a call into
264 * Haskell using one of the rts_eval() functions. This data is not
265 * normally freed until hs_exit(). If you want to free it earlier
266 * than this, perhaps because the thread is about to exit, then call
267 * rts_done() from the thread.
268 *
269 * It is safe to make more rts_eval() calls after calling rts_done(),
270 * but the next one will cause allocation of the thread-local memory
271 * again.
272 */
273 void rts_done (void);
274
275 /* --------------------------------------------------------------------------
276 Wrapper closures
277
278 These are used by foreign export and foreign import "wrapper" stubs.
279 ----------------------------------------------------------------------- */
280
281 // When producing Windows DLLs the we need to know which symbols are in the
282 // local package/DLL vs external ones.
283 //
284 // Note that RtsAPI.h is also included by foreign export stubs in
285 // the base package itself.
286 //
287 #if defined(COMPILING_WINDOWS_DLL) && !defined(COMPILING_BASE_PACKAGE)
288 __declspec(dllimport) extern StgWord base_GHCziTopHandler_runIO_closure[];
289 __declspec(dllimport) extern StgWord base_GHCziTopHandler_runNonIO_closure[];
290 #else
291 extern StgWord base_GHCziTopHandler_runIO_closure[];
292 extern StgWord base_GHCziTopHandler_runNonIO_closure[];
293 #endif
294
295 #define runIO_closure base_GHCziTopHandler_runIO_closure
296 #define runNonIO_closure base_GHCziTopHandler_runNonIO_closure
297
298 /* ------------------------------------------------------------------------ */
299
300 #ifdef __cplusplus
301 }
302 #endif
303
304 #endif /* RTSAPI_H */