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