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