src/common/core/runtime.d

   1 /**
   2  * The runtime module exposes information specific to the D runtime code.
   3  *
   4  * Copyright: Copyright (c) 2005-2008, The D Runtime Project
   5  * License:   BSD Style, see LICENSE
   6  * Authors:   Sean Kelly
   7  */
   8 module core.runtime;
   9
  10
  11 private
  12 {
  13     extern (C) bool rt_isHalting();
  14
  15     alias bool function() ModuleUnitTester;
  16     alias bool function(Object) CollectHandler;
  17     alias Exception.TraceInfo function( void* ptr = null ) TraceHandler;
  18
  19     extern (C) void rt_setCollectHandler( CollectHandler h );
  20     extern (C) void rt_setTraceHandler( TraceHandler h );
  21
  22     alias void delegate( Exception ) ExceptionHandler;
  23     extern (C) bool rt_init( ExceptionHandler dg = null );
  24     extern (C) bool rt_term( ExceptionHandler dg = null );
  25
  26     extern (C) void* rt_loadLibrary( in char[] name );
  27     extern (C) void  rt_unloadLibrary( void* ptr );
  28 }
  29
  30
  31 ///////////////////////////////////////////////////////////////////////////////
  32 // Runtime
  33 ///////////////////////////////////////////////////////////////////////////////
  34
  35
  36 /**
  37  * This struct encapsulates all functionality related to the underlying runtime
  38  * module for the calling context.
  39  */
  40 struct Runtime
  41 {
  42     /**
  43      * Initializes the runtime.  This call is to be used in instances where the
  44      * standard program initialization process is not executed.  This is most
  45      * often in shared libraries or in libraries linked to a C program.
  46      *
  47      * Params:
  48      *  dg = A delegate which will receive any exception thrown during the
  49      *       initialization process or null if such exceptions should be
  50      *       discarded.
  51      *
  52      * Returns:
  53      *  true if initialization succeeds and false if initialization fails.
  54      */
  55     static bool initialize( void delegate( Exception ) dg = null )
  56     {
  57         return rt_init( dg );
  58     }
  59
  60
  61     /**
  62      * Terminates the runtime.  This call is to be used in instances where the
  63      * standard program termination process will not be not executed.  This is
  64      * most often in shared libraries or in libraries linked to a C program.
  65      *
  66      * Params:
  67      *  dg = A delegate which will receive any exception thrown during the
  68      *       termination process or null if such exceptions should be
  69      *       discarded.
  70      *
  71      * Returns:
  72      *  true if termination succeeds and false if termination fails.
  73      */
  74     static bool terminate( void delegate( Exception ) dg = null )
  75     {
  76         return rt_term( dg );
  77     }
  78
  79
  80     /**
  81      * Returns true if the runtime is halting.  Under normal circumstances,
  82      * this will be set between the time that normal application code has
  83      * exited and before module dtors are called.
  84      *
  85      * Returns:
  86      *  true if the runtime is halting.
  87      */
  88     static bool isHalting()
  89     {
  90         return rt_isHalting();
  91     }
  92
  93
  94     /**
  95      * Locates a dynamic library with the supplied library name and dynamically
  96      * loads it into the caller's address space.  If the library contains a D
  97      * runtime it will be integrated with the current runtime.
  98      *
  99      * Params:
 100      *  name = The name of the dynamic library to load.
 101      *
 102      * Returns:
 103      *  A reference to the library or null on error.
 104      */
 105     static void* loadLibrary( in char[] name )
 106     {
 107         return rt_loadLibrary( name );
 108     }
 109
 110
 111     /**
 112      * Unloads the dynamic library referenced by p.  If this library contains a
 113      * D runtime then any necessary finalization or cleanup of that runtime
 114      * will be performed.
 115      *
 116      * Params:
 117      *  p = A reference to the library to unload.
 118      */
 119     static void unloadLibrary( void* p )
 120     {
 121         rt_unloadLibrary( p );
 122     }
 123
 124
 125     /**
 126      * Overrides the default trace mechanism with s user-supplied version.  A
 127      * trace represents the context from which an exception was thrown, and the
 128      * trace handler will be called when this occurs.  The pointer supplied to
 129      * this routine indicates the base address from which tracing should occur.
 130      * If the supplied pointer is null then the trace routine should determine
 131      * an appropriate calling context from which to begin the trace.
 132      *
 133      * Params:
 134      *  h = The new trace handler.  Set to null to use the default handler.
 135      */
 136     static void traceHandler( TraceHandler h )
 137     {
 138         rt_setTraceHandler( h );
 139     }
 140
 141
 142     /**
 143      * Overrides the default collect hander with a user-supplied version.  This
 144      * routine will be called for each resource object that is finalized in a
 145      * non-deterministic manner--typically during a garbage collection cycle.
 146      * If the supplied routine returns true then the object's dtor will called
 147      * as normal, but if the routine returns false than the dtor will not be
 148      * called.  The default behavior is for all object dtors to be called.
 149      *
 150      * Params:
 151      *  h = The new collect handler.  Set to null to use the default handler.
 152      */
 153     static void collectHandler( CollectHandler h )
 154     {
 155         rt_setCollectHandler( h );
 156     }
 157
 158
 159     /**
 160      * Overrides the default module unit tester with a user-supplied version.
 161      * This routine will be called once on program initialization.  The return
 162      * value of this routine indicates to the runtime whether the body of the
 163      * program will be executed.
 164      *
 165      * Params:
 166      *  h = The new unit tester.  Set to null to use the default unit tester.
 167      */
 168     static void moduleUnitTester( ModuleUnitTester h )
 169     {
 170         sm_moduleUnitTester = h;
 171     }
 172
 173
 174 private:
 175     static ModuleUnitTester sm_moduleUnitTester = null;
 176 }
 177
 178
 179 ///////////////////////////////////////////////////////////////////////////////
 180 // Overridable Callbacks
 181 ///////////////////////////////////////////////////////////////////////////////
 182
 183
 184 /**
 185  * This routine is called by the runtime to run module unit tests on startup.
 186  * The user-supplied unit tester will be called if one has been supplied,
 187  * otherwise all unit tests will be run in sequence.
 188  *
 189  * Returns:
 190  *  true if execution should continue after testing is complete and false if
 191  *  not.  Default behavior is to return true.
 192  */
 193 extern (C) bool runModuleUnitTests()
 194 {
 195     if( Runtime.sm_moduleUnitTester is null )
 196     {
 197         foreach( m; ModuleInfo )
 198         {
 199             if( m.unitTest )
 200                 m.unitTest();
 201         }
 202         return true;
 203     }
 204     return Runtime.sm_moduleUnitTester();
 205 }