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