Merge branch 'master' of http://darcs.haskell.org//ghc
[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 Capability *
186 rts_eval (Capability *, HaskellObj p, /*out*/HaskellObj *ret);
187
188 Capability *
189 rts_eval_ (Capability *, HaskellObj p, unsigned int stack_size,
190 /*out*/HaskellObj *ret);
191
192 Capability *
193 rts_evalIO (Capability *, HaskellObj p, /*out*/HaskellObj *ret);
194
195 Capability *
196 rts_evalStableIO (Capability *, HsStablePtr s, /*out*/HsStablePtr *ret);
197
198 Capability *
199 rts_evalLazyIO (Capability *, HaskellObj p, /*out*/HaskellObj *ret);
200
201 Capability *
202 rts_evalLazyIO_ (Capability *, HaskellObj p, unsigned int stack_size,
203 /*out*/HaskellObj *ret);
204
205 void
206 rts_checkSchedStatus (char* site, Capability *);
207
208 SchedulerStatus
209 rts_getSchedStatus (Capability *cap);
210
211 /* --------------------------------------------------------------------------
212 Wrapper closures
213
214 These are used by foreign export and foreign import "wrapper" stubs.
215 ----------------------------------------------------------------------- */
216
217 // When producing Windows DLLs the we need to know which symbols are in the
218 // local package/DLL vs external ones.
219 //
220 // Note that RtsAPI.h is also included by foreign export stubs in
221 // the base package itself.
222 //
223 #if defined(mingw32_HOST_OS) && defined(__PIC__) && !defined(COMPILING_BASE_PACKAGE)
224 __declspec(dllimport) extern StgWord base_GHCziTopHandler_runIO_closure[];
225 __declspec(dllimport) extern StgWord base_GHCziTopHandler_runNonIO_closure[];
226 #else
227 extern StgWord base_GHCziTopHandler_runIO_closure[];
228 extern StgWord base_GHCziTopHandler_runNonIO_closure[];
229 #endif
230
231 #define runIO_closure base_GHCziTopHandler_runIO_closure
232 #define runNonIO_closure base_GHCziTopHandler_runNonIO_closure
233
234 /* ------------------------------------------------------------------------ */
235
236 #ifdef __cplusplus
237 }
238 #endif
239
240 #endif /* RTSAPI_H */