Comments only
[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  * --------------------------------------------------------------------------*/
8
9 #ifndef RTSAPI_H
10 #define RTSAPI_H
11
12 #ifdef __cplusplus
13 extern "C" {
14 #endif
15
16 #include "HsFFI.h"
17
18 /*
19  * Running the scheduler
20  */
21 typedef enum {
22     NoStatus,    /* not finished yet */
23     Success,     /* completed successfully */
24     Killed,      /* uncaught exception */
25     Interrupted  /* stopped in response to a call to interruptStgRts */
26 } SchedulerStatus;
27
28 typedef StgClosure *HaskellObj;
29
30 /*
31  * An abstract type representing the token returned by rts_lock() and
32  * used when allocating objects and threads in the RTS.
33  */
34 typedef struct Capability_ Capability;
35
36 /* ----------------------------------------------------------------------------
37    Starting up and shutting down the Haskell RTS.
38    ------------------------------------------------------------------------- */
39 extern void startupHaskell         ( int argc, char *argv[], 
40                                      void (*init_root)(void) );
41 extern void shutdownHaskell        ( void );
42 extern void shutdownHaskellAndExit ( int exitCode );
43 extern void getProgArgv            ( int *argc, char **argv[] );
44 extern void setProgArgv            ( int argc, char *argv[] );
45
46 /* exit() override */
47 extern void (*exitFn)(int);
48
49 /* ----------------------------------------------------------------------------
50    Locking.
51    
52    You have to surround all access to the RtsAPI with these calls.
53    ------------------------------------------------------------------------- */
54    
55 // acquires a token which may be used to create new objects and
56 // evaluate them.
57 Capability *rts_lock (void);
58
59 // releases the token acquired with rts_lock().
60 void rts_unlock (Capability *token);
61
62 /* ----------------------------------------------------------------------------
63    Building Haskell objects from C datatypes.
64    ------------------------------------------------------------------------- */
65 HaskellObj   rts_mkChar       ( Capability *, HsChar   c );
66 HaskellObj   rts_mkInt        ( Capability *, HsInt    i );
67 HaskellObj   rts_mkInt8       ( Capability *, HsInt8   i );
68 HaskellObj   rts_mkInt16      ( Capability *, HsInt16  i );
69 HaskellObj   rts_mkInt32      ( Capability *, HsInt32  i );
70 HaskellObj   rts_mkInt64      ( Capability *, HsInt64  i );
71 HaskellObj   rts_mkWord       ( Capability *, HsWord   w );
72 HaskellObj   rts_mkWord8      ( Capability *, HsWord8  w );
73 HaskellObj   rts_mkWord16     ( Capability *, HsWord16 w );
74 HaskellObj   rts_mkWord32     ( Capability *, HsWord32 w );
75 HaskellObj   rts_mkWord64     ( Capability *, HsWord64 w );
76 HaskellObj   rts_mkPtr        ( Capability *, HsPtr    a );
77 HaskellObj   rts_mkFunPtr     ( Capability *, HsFunPtr a );
78 HaskellObj   rts_mkFloat      ( Capability *, HsFloat  f );
79 HaskellObj   rts_mkDouble     ( Capability *, HsDouble f );
80 HaskellObj   rts_mkStablePtr  ( Capability *, HsStablePtr s );
81 HaskellObj   rts_mkBool       ( Capability *, HsBool   b );
82 HaskellObj   rts_mkString     ( Capability *, char    *s );
83
84 HaskellObj   rts_apply        ( Capability *, HaskellObj, HaskellObj );
85
86 /* ----------------------------------------------------------------------------
87    Deconstructing Haskell objects
88    ------------------------------------------------------------------------- */
89 HsChar       rts_getChar      ( HaskellObj );
90 HsInt        rts_getInt       ( HaskellObj );
91 HsInt8       rts_getInt8      ( HaskellObj );
92 HsInt16      rts_getInt16     ( HaskellObj );
93 HsInt32      rts_getInt32     ( HaskellObj );
94 HsInt64      rts_getInt64     ( HaskellObj );
95 HsWord       rts_getWord      ( HaskellObj );
96 HsWord8      rts_getWord8     ( HaskellObj );
97 HsWord16     rts_getWord16    ( HaskellObj );
98 HsWord32     rts_getWord32    ( HaskellObj );
99 HsWord64     rts_getWord64    ( HaskellObj );
100 HsPtr        rts_getPtr       ( HaskellObj );
101 HsFunPtr     rts_getFunPtr    ( HaskellObj );
102 HsFloat      rts_getFloat     ( HaskellObj );
103 HsDouble     rts_getDouble    ( HaskellObj );
104 HsStablePtr  rts_getStablePtr ( HaskellObj );
105 HsBool       rts_getBool      ( HaskellObj );
106
107 /* ----------------------------------------------------------------------------
108    Evaluating Haskell expressions
109
110    The versions ending in '_' allow you to specify an initial stack size.
111    Note that these calls may cause Garbage Collection, so all HaskellObj
112    references are rendered invalid by these calls.
113    ------------------------------------------------------------------------- */
114 Capability * 
115 rts_eval (Capability *, HaskellObj p, /*out*/HaskellObj *ret);
116
117 Capability * 
118 rts_eval_ (Capability *, HaskellObj p, unsigned int stack_size, 
119            /*out*/HaskellObj *ret);
120
121 Capability * 
122 rts_evalIO (Capability *, HaskellObj p, /*out*/HaskellObj *ret);
123
124 Capability *
125 rts_evalStableIO (Capability *, HsStablePtr s, /*out*/HsStablePtr *ret);
126
127 Capability * 
128 rts_evalLazyIO (Capability *, HaskellObj p, /*out*/HaskellObj *ret);
129
130 Capability * 
131 rts_evalLazyIO_ (Capability *, HaskellObj p, unsigned int stack_size, 
132                  /*out*/HaskellObj *ret);
133
134 void
135 rts_checkSchedStatus (char* site, Capability *);
136
137 SchedulerStatus
138 rts_getSchedStatus (Capability *cap);
139
140 /* --------------------------------------------------------------------------
141    Wrapper closures
142
143    These are used by foreign export and foreign import "wrapper" stubs.
144    ----------------------------------------------------------------------- */
145
146 extern StgWord base_GHCziTopHandler_runIO_closure[];
147 extern StgWord base_GHCziTopHandler_runNonIO_closure[];
148 #define runIO_closure             base_GHCziTopHandler_runIO_closure
149 #define runNonIO_closure          base_GHCziTopHandler_runNonIO_closure
150
151 /* ------------------------------------------------------------------------ */
152
153 #ifdef __cplusplus
154 }
155 #endif
156
157 #endif /* RTSAPI_H */