remove ^Ms; comment updates
[ghc-hetmet.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    Starting up and shutting down the Haskell RTS.
42    ------------------------------------------------------------------------- */
43 extern void startupHaskell         ( int argc, char *argv[], 
44                                      void (*init_root)(void) );
45 extern void shutdownHaskell        ( void );
46 extern void shutdownHaskellAndExit ( int exitCode );
47 extern void getProgArgv            ( int *argc, char **argv[] );
48 extern void setProgArgv            ( int argc, char *argv[] );
49 extern void getFullProgArgv        ( int *argc, char **argv[] );
50 extern void setFullProgArgv        ( int argc, char *argv[] );
51 extern void freeFullProgArgv       ( void ) ;
52
53 #ifndef mingw32_HOST_OS
54 extern void shutdownHaskellAndSignal (int sig);
55 #endif
56
57 /* exit() override */
58 extern void (*exitFn)(int);
59
60 /* ----------------------------------------------------------------------------
61    Locking.
62    
63    You have to surround all access to the RtsAPI with these calls.
64    ------------------------------------------------------------------------- */
65    
66 // acquires a token which may be used to create new objects and
67 // evaluate them.
68 Capability *rts_lock (void);
69
70 // releases the token acquired with rts_lock().
71 void rts_unlock (Capability *token);
72
73 // If you are in a context where you know you have a current capability but
74 // do not know what it is, then use this to get it. Basically this only
75 // applies to "unsafe" foreign calls (as unsafe foreign calls are made with
76 // the capability held).
77 //
78 // WARNING: There is *no* guarantee this returns anything sensible (eg NULL)
79 // when there is no current capability.
80 Capability *rts_unsafeGetMyCapability (void);
81
82 /* ----------------------------------------------------------------------------
83    Building Haskell objects from C datatypes.
84    ------------------------------------------------------------------------- */
85 HaskellObj   rts_mkChar       ( Capability *, HsChar   c );
86 HaskellObj   rts_mkInt        ( Capability *, HsInt    i );
87 HaskellObj   rts_mkInt8       ( Capability *, HsInt8   i );
88 HaskellObj   rts_mkInt16      ( Capability *, HsInt16  i );
89 HaskellObj   rts_mkInt32      ( Capability *, HsInt32  i );
90 HaskellObj   rts_mkInt64      ( Capability *, HsInt64  i );
91 HaskellObj   rts_mkWord       ( Capability *, HsWord   w );
92 HaskellObj   rts_mkWord8      ( Capability *, HsWord8  w );
93 HaskellObj   rts_mkWord16     ( Capability *, HsWord16 w );
94 HaskellObj   rts_mkWord32     ( Capability *, HsWord32 w );
95 HaskellObj   rts_mkWord64     ( Capability *, HsWord64 w );
96 HaskellObj   rts_mkPtr        ( Capability *, HsPtr    a );
97 HaskellObj   rts_mkFunPtr     ( Capability *, HsFunPtr a );
98 HaskellObj   rts_mkFloat      ( Capability *, HsFloat  f );
99 HaskellObj   rts_mkDouble     ( Capability *, HsDouble f );
100 HaskellObj   rts_mkStablePtr  ( Capability *, HsStablePtr s );
101 HaskellObj   rts_mkBool       ( Capability *, HsBool   b );
102 HaskellObj   rts_mkString     ( Capability *, char    *s );
103
104 HaskellObj   rts_apply        ( Capability *, HaskellObj, HaskellObj );
105
106 /* ----------------------------------------------------------------------------
107    Deconstructing Haskell objects
108    ------------------------------------------------------------------------- */
109 HsChar       rts_getChar      ( HaskellObj );
110 HsInt        rts_getInt       ( HaskellObj );
111 HsInt8       rts_getInt8      ( HaskellObj );
112 HsInt16      rts_getInt16     ( HaskellObj );
113 HsInt32      rts_getInt32     ( HaskellObj );
114 HsInt64      rts_getInt64     ( HaskellObj );
115 HsWord       rts_getWord      ( HaskellObj );
116 HsWord8      rts_getWord8     ( HaskellObj );
117 HsWord16     rts_getWord16    ( HaskellObj );
118 HsWord32     rts_getWord32    ( HaskellObj );
119 HsWord64     rts_getWord64    ( HaskellObj );
120 HsPtr        rts_getPtr       ( HaskellObj );
121 HsFunPtr     rts_getFunPtr    ( HaskellObj );
122 HsFloat      rts_getFloat     ( HaskellObj );
123 HsDouble     rts_getDouble    ( HaskellObj );
124 HsStablePtr  rts_getStablePtr ( HaskellObj );
125 HsBool       rts_getBool      ( HaskellObj );
126
127 /* ----------------------------------------------------------------------------
128    Evaluating Haskell expressions
129
130    The versions ending in '_' allow you to specify an initial stack size.
131    Note that these calls may cause Garbage Collection, so all HaskellObj
132    references are rendered invalid by these calls.
133    ------------------------------------------------------------------------- */
134 Capability * 
135 rts_eval (Capability *, HaskellObj p, /*out*/HaskellObj *ret);
136
137 Capability * 
138 rts_eval_ (Capability *, HaskellObj p, unsigned int stack_size, 
139            /*out*/HaskellObj *ret);
140
141 Capability * 
142 rts_evalIO (Capability *, HaskellObj p, /*out*/HaskellObj *ret);
143
144 Capability *
145 rts_evalStableIO (Capability *, HsStablePtr s, /*out*/HsStablePtr *ret);
146
147 Capability * 
148 rts_evalLazyIO (Capability *, HaskellObj p, /*out*/HaskellObj *ret);
149
150 Capability * 
151 rts_evalLazyIO_ (Capability *, HaskellObj p, unsigned int stack_size, 
152                  /*out*/HaskellObj *ret);
153
154 void
155 rts_checkSchedStatus (char* site, Capability *);
156
157 SchedulerStatus
158 rts_getSchedStatus (Capability *cap);
159
160 /* --------------------------------------------------------------------------
161    Wrapper closures
162
163    These are used by foreign export and foreign import "wrapper" stubs.
164    ----------------------------------------------------------------------- */
165
166 // When producing Windows DLLs the we need to know which symbols are in the 
167 //      local package/DLL vs external ones. 
168 //
169 //      Note that RtsAPI.h is also included by foreign export stubs in
170 //      the base package itself.
171 //
172 #if defined(mingw32_HOST_OS) && defined(__PIC__) && !defined(COMPILING_BASE_PACKAGE)
173 __declspec(dllimport) extern StgWord base_GHCziTopHandler_runIO_closure[];
174 __declspec(dllimport) extern StgWord base_GHCziTopHandler_runNonIO_closure[];
175 #else
176 extern StgWord base_GHCziTopHandler_runIO_closure[];
177 extern StgWord base_GHCziTopHandler_runNonIO_closure[];
178 #endif
179
180 #define runIO_closure     base_GHCziTopHandler_runIO_closure
181 #define runNonIO_closure  base_GHCziTopHandler_runNonIO_closure
182
183 /* ------------------------------------------------------------------------ */
184
185 #ifdef __cplusplus
186 }
187 #endif
188
189 #endif /* RTSAPI_H */