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 */