Distinguish between hs-main cases when giving rtsopts advice.
[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://hackage.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 )
98 #if __GNUC__ >= 3
99 __attribute__((__noreturn__))
100 #endif
101 ;
102
103 #ifndef mingw32_HOST_OS
104 extern void shutdownHaskellAndSignal (int sig);
105 #endif
106
107 extern void getProgArgv ( int *argc, char **argv[] );
108 extern void setProgArgv ( int argc, char *argv[] );
109 extern void getFullProgArgv ( int *argc, char **argv[] );
110 extern void setFullProgArgv ( int argc, char *argv[] );
111 extern void freeFullProgArgv ( void ) ;
112
113 /* exit() override */
114 extern void (*exitFn)(int);
115
116 /* ----------------------------------------------------------------------------
117 Locking.
118
119 You have to surround all access to the RtsAPI with these calls.
120 ------------------------------------------------------------------------- */
121
122 // acquires a token which may be used to create new objects and
123 // evaluate them.
124 Capability *rts_lock (void);
125
126 // releases the token acquired with rts_lock().
127 void rts_unlock (Capability *token);
128
129 // If you are in a context where you know you have a current capability but
130 // do not know what it is, then use this to get it. Basically this only
131 // applies to "unsafe" foreign calls (as unsafe foreign calls are made with
132 // the capability held).
133 //
134 // WARNING: There is *no* guarantee this returns anything sensible (eg NULL)
135 // when there is no current capability.
136 Capability *rts_unsafeGetMyCapability (void);
137
138 /* ----------------------------------------------------------------------------
139 Building Haskell objects from C datatypes.
140 ------------------------------------------------------------------------- */
141 HaskellObj rts_mkChar ( Capability *, HsChar c );
142 HaskellObj rts_mkInt ( Capability *, HsInt i );
143 HaskellObj rts_mkInt8 ( Capability *, HsInt8 i );
144 HaskellObj rts_mkInt16 ( Capability *, HsInt16 i );
145 HaskellObj rts_mkInt32 ( Capability *, HsInt32 i );
146 HaskellObj rts_mkInt64 ( Capability *, HsInt64 i );
147 HaskellObj rts_mkWord ( Capability *, HsWord w );
148 HaskellObj rts_mkWord8 ( Capability *, HsWord8 w );
149 HaskellObj rts_mkWord16 ( Capability *, HsWord16 w );
150 HaskellObj rts_mkWord32 ( Capability *, HsWord32 w );
151 HaskellObj rts_mkWord64 ( Capability *, HsWord64 w );
152 HaskellObj rts_mkPtr ( Capability *, HsPtr a );
153 HaskellObj rts_mkFunPtr ( Capability *, HsFunPtr a );
154 HaskellObj rts_mkFloat ( Capability *, HsFloat f );
155 HaskellObj rts_mkDouble ( Capability *, HsDouble f );
156 HaskellObj rts_mkStablePtr ( Capability *, HsStablePtr s );
157 HaskellObj rts_mkBool ( Capability *, HsBool b );
158 HaskellObj rts_mkString ( Capability *, char *s );
159
160 HaskellObj rts_apply ( Capability *, HaskellObj, HaskellObj );
161
162 /* ----------------------------------------------------------------------------
163 Deconstructing Haskell objects
164 ------------------------------------------------------------------------- */
165 HsChar rts_getChar ( HaskellObj );
166 HsInt rts_getInt ( HaskellObj );
167 HsInt8 rts_getInt8 ( HaskellObj );
168 HsInt16 rts_getInt16 ( HaskellObj );
169 HsInt32 rts_getInt32 ( HaskellObj );
170 HsInt64 rts_getInt64 ( HaskellObj );
171 HsWord rts_getWord ( HaskellObj );
172 HsWord8 rts_getWord8 ( HaskellObj );
173 HsWord16 rts_getWord16 ( HaskellObj );
174 HsWord32 rts_getWord32 ( HaskellObj );
175 HsWord64 rts_getWord64 ( HaskellObj );
176 HsPtr rts_getPtr ( HaskellObj );
177 HsFunPtr rts_getFunPtr ( HaskellObj );
178 HsFloat rts_getFloat ( HaskellObj );
179 HsDouble rts_getDouble ( HaskellObj );
180 HsStablePtr rts_getStablePtr ( HaskellObj );
181 HsBool rts_getBool ( HaskellObj );
182
183 /* ----------------------------------------------------------------------------
184 Evaluating Haskell expressions
185
186 The versions ending in '_' allow you to specify an initial stack size.
187 Note that these calls may cause Garbage Collection, so all HaskellObj
188 references are rendered invalid by these calls.
189
190 All of these functions take a (Capability **) - there is a
191 Capability pointer both input and output. We use an inout
192 parameter because this is less error-prone for the client than a
193 return value - the client could easily forget to use the return
194 value, whereas incorrectly using an inout parameter will usually
195 result in a type error.
196 ------------------------------------------------------------------------- */
197
198 void rts_eval (/* inout */ Capability **,
199 /* in */ HaskellObj p,
200 /* out */ HaskellObj *ret);
201
202 void rts_eval_ (/* inout */ Capability **,
203 /* in */ HaskellObj p,
204 /* in */ unsigned int stack_size,
205 /* out */ HaskellObj *ret);
206
207 void rts_evalIO (/* inout */ Capability **,
208 /* in */ HaskellObj p,
209 /* out */ HaskellObj *ret);
210
211 void rts_evalStableIO (/* inout */ Capability **,
212 /* in */ HsStablePtr s,
213 /* out */ HsStablePtr *ret);
214
215 void rts_evalLazyIO (/* inout */ Capability **,
216 /* in */ HaskellObj p,
217 /* out */ HaskellObj *ret);
218
219 void rts_evalLazyIO_ (/* inout */ Capability **,
220 /* in */ HaskellObj p,
221 /* in */ unsigned int stack_size,
222 /* out */ HaskellObj *ret);
223
224 void rts_checkSchedStatus (char* site, Capability *);
225
226 SchedulerStatus rts_getSchedStatus (Capability *cap);
227
228 /* --------------------------------------------------------------------------
229 Wrapper closures
230
231 These are used by foreign export and foreign import "wrapper" stubs.
232 ----------------------------------------------------------------------- */
233
234 // When producing Windows DLLs the we need to know which symbols are in the
235 // local package/DLL vs external ones.
236 //
237 // Note that RtsAPI.h is also included by foreign export stubs in
238 // the base package itself.
239 //
240 #if defined(COMPILING_WINDOWS_DLL) && !defined(COMPILING_BASE_PACKAGE)
241 __declspec(dllimport) extern StgWord base_GHCziTopHandler_runIO_closure[];
242 __declspec(dllimport) extern StgWord base_GHCziTopHandler_runNonIO_closure[];
243 #else
244 extern StgWord base_GHCziTopHandler_runIO_closure[];
245 extern StgWord base_GHCziTopHandler_runNonIO_closure[];
246 #endif
247
248 #define runIO_closure base_GHCziTopHandler_runIO_closure
249 #define runNonIO_closure base_GHCziTopHandler_runNonIO_closure
250
251 /* ------------------------------------------------------------------------ */
252
253 #ifdef __cplusplus
254 }
255 #endif
256
257 #endif /* RTSAPI_H */