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