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