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