RtsAPI.h 6.37 KB
Newer Older
1
/* ----------------------------------------------------------------------------
2
 *
3
 * (c) The GHC Team, 1998-2004
4 5 6 7 8 9 10 11
 *
 * API for invoking Haskell functions via the RTS
 *
 * --------------------------------------------------------------------------*/

#ifndef RTSAPI_H
#define RTSAPI_H

12 13 14 15
#ifdef __cplusplus
extern "C" {
#endif

16 17
#include "HsFFI.h"

sof's avatar
sof committed
18 19 20 21
/*
 * Running the scheduler
 */
typedef enum {
22 23 24
    NoStatus,    /* not finished yet */
    Success,	 /* completed successfully */
    Killed,	 /* uncaught exception */
25 26
    Interrupted, /* stopped in response to a call to interruptStgRts */
    HeapExhausted /* out of memory */
sof's avatar
sof committed
27
} SchedulerStatus;
28

Simon Marlow's avatar
Simon Marlow committed
29
typedef struct StgClosure_ *HaskellObj;
30

31 32 33 34 35 36
/*
 * An abstract type representing the token returned by rts_lock() and
 * used when allocating objects and threads in the RTS.
 */
typedef struct Capability_ Capability;

37 38 39
/* ----------------------------------------------------------------------------
   Starting up and shutting down the Haskell RTS.
   ------------------------------------------------------------------------- */
40 41
extern void startupHaskell         ( int argc, char *argv[], 
				     void (*init_root)(void) );
42
extern void shutdownHaskell        ( void );
sof's avatar
sof committed
43
extern void shutdownHaskellAndExit ( int exitCode );
44
extern void getProgArgv            ( int *argc, char **argv[] );
45
extern void setProgArgv            ( int argc, char *argv[] );
46 47
extern void getFullProgArgv        ( int *argc, char **argv[] );
extern void setFullProgArgv        ( int argc, char *argv[] );
48

Simon Marlow's avatar
Simon Marlow committed
49 50 51 52
#ifndef mingw32_HOST_OS
extern void shutdownHaskellAndSignal (int sig);
#endif

53 54
/* exit() override */
extern void (*exitFn)(int);
55 56 57 58

/* ----------------------------------------------------------------------------
   Locking.
   
59
   You have to surround all access to the RtsAPI with these calls.
60 61
   ------------------------------------------------------------------------- */
   
62 63 64
// acquires a token which may be used to create new objects and
// evaluate them.
Capability *rts_lock (void);
65

66 67
// releases the token acquired with rts_lock().
void rts_unlock (Capability *token);
68

69 70 71 72 73 74 75 76 77
// If you are in a context where you know you have a current capability but
// do not know what it is, then use this to get it. Basically this only
// applies to "unsafe" foreign calls (as unsafe foreign calls are made with
// the capability held).
//
// WARNING: There is *no* guarantee this returns anything sensible (eg NULL)
// when there is no current capability.
Capability *rts_unsafeGetMyCapability (void);

78 79 80
/* ----------------------------------------------------------------------------
   Building Haskell objects from C datatypes.
   ------------------------------------------------------------------------- */
81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100
HaskellObj   rts_mkChar       ( Capability *, HsChar   c );
HaskellObj   rts_mkInt        ( Capability *, HsInt    i );
HaskellObj   rts_mkInt8       ( Capability *, HsInt8   i );
HaskellObj   rts_mkInt16      ( Capability *, HsInt16  i );
HaskellObj   rts_mkInt32      ( Capability *, HsInt32  i );
HaskellObj   rts_mkInt64      ( Capability *, HsInt64  i );
HaskellObj   rts_mkWord       ( Capability *, HsWord   w );
HaskellObj   rts_mkWord8      ( Capability *, HsWord8  w );
HaskellObj   rts_mkWord16     ( Capability *, HsWord16 w );
HaskellObj   rts_mkWord32     ( Capability *, HsWord32 w );
HaskellObj   rts_mkWord64     ( Capability *, HsWord64 w );
HaskellObj   rts_mkPtr        ( Capability *, HsPtr    a );
HaskellObj   rts_mkFunPtr     ( Capability *, HsFunPtr a );
HaskellObj   rts_mkFloat      ( Capability *, HsFloat  f );
HaskellObj   rts_mkDouble     ( Capability *, HsDouble f );
HaskellObj   rts_mkStablePtr  ( Capability *, HsStablePtr s );
HaskellObj   rts_mkBool       ( Capability *, HsBool   b );
HaskellObj   rts_mkString     ( Capability *, char    *s );

HaskellObj   rts_apply        ( Capability *, HaskellObj, HaskellObj );
101 102 103 104

/* ----------------------------------------------------------------------------
   Deconstructing Haskell objects
   ------------------------------------------------------------------------- */
105 106
HsChar       rts_getChar      ( HaskellObj );
HsInt        rts_getInt       ( HaskellObj );
sof's avatar
sof committed
107 108
HsInt8       rts_getInt8      ( HaskellObj );
HsInt16      rts_getInt16     ( HaskellObj );
109
HsInt32      rts_getInt32     ( HaskellObj );
sof's avatar
sof committed
110
HsInt64      rts_getInt64     ( HaskellObj );
111
HsWord       rts_getWord      ( HaskellObj );
sof's avatar
sof committed
112 113
HsWord8      rts_getWord8     ( HaskellObj );
HsWord16     rts_getWord16    ( HaskellObj );
114
HsWord32     rts_getWord32    ( HaskellObj );
sof's avatar
sof committed
115
HsWord64     rts_getWord64    ( HaskellObj );
116
HsPtr        rts_getPtr       ( HaskellObj );
117
HsFunPtr     rts_getFunPtr    ( HaskellObj );
118 119 120 121
HsFloat      rts_getFloat     ( HaskellObj );
HsDouble     rts_getDouble    ( HaskellObj );
HsStablePtr  rts_getStablePtr ( HaskellObj );
HsBool       rts_getBool      ( HaskellObj );
122 123 124 125 126

/* ----------------------------------------------------------------------------
   Evaluating Haskell expressions

   The versions ending in '_' allow you to specify an initial stack size.
127 128
   Note that these calls may cause Garbage Collection, so all HaskellObj
   references are rendered invalid by these calls.
129
   ------------------------------------------------------------------------- */
130 131
Capability * 
rts_eval (Capability *, HaskellObj p, /*out*/HaskellObj *ret);
132

133 134 135
Capability * 
rts_eval_ (Capability *, HaskellObj p, unsigned int stack_size, 
	   /*out*/HaskellObj *ret);
136

137 138
Capability * 
rts_evalIO (Capability *, HaskellObj p, /*out*/HaskellObj *ret);
139

140 141
Capability *
rts_evalStableIO (Capability *, HsStablePtr s, /*out*/HsStablePtr *ret);
142

143 144
Capability * 
rts_evalLazyIO (Capability *, HaskellObj p, /*out*/HaskellObj *ret);
145

146 147 148
Capability * 
rts_evalLazyIO_ (Capability *, HaskellObj p, unsigned int stack_size, 
		 /*out*/HaskellObj *ret);
149 150

void
151 152 153 154
rts_checkSchedStatus (char* site, Capability *);

SchedulerStatus
rts_getSchedStatus (Capability *cap);
155

156 157 158 159 160 161
/* --------------------------------------------------------------------------
   Wrapper closures

   These are used by foreign export and foreign import "wrapper" stubs.
   ----------------------------------------------------------------------- */

162 163 164 165
extern StgWord base_GHCziTopHandler_runIO_closure[];
extern StgWord base_GHCziTopHandler_runNonIO_closure[];
#define runIO_closure		  base_GHCziTopHandler_runIO_closure
#define runNonIO_closure	  base_GHCziTopHandler_runNonIO_closure
166 167

/* ------------------------------------------------------------------------ */
168 169 170 171 172

#ifdef __cplusplus
}
#endif

173
#endif /* RTSAPI_H */