src/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 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
  27
  28 ///////////////////////////////////////////////////////////////////////////////
  29 // Runtime
  30 ///////////////////////////////////////////////////////////////////////////////
  31
  32
  33 /**
  34  * This struct encapsulates all functionality related to the underlying runtime
  35  * module for the calling context.
  36  */
  37 struct Runtime
  38 {
  39     /**
  40      * Initializes the runtime.  This call is to be used in instances where the
  41      * standard program initialization process is not executed.  This is most
  42      * often in shared libraries or in libraries linked to a C program.
  43      *
  44      * Params:
  45      *  dg = A delegate which will receive any exception thrown during the
  46      *       initialization process or null if such exceptions should be
  47      *       discarded.
  48      *
  49      * Returns:
  50      *  true if initialization succeeds and false if initialization fails.
  51      */
  52     static bool initialize( void delegate( Exception ) dg = null )
  53     {
  54         return rt_init( dg );
  55     }
  56
  57
  58     /**
  59      * Terminates the runtime.  This call is to be used in instances where the
  60      * standard program termination process will not be not executed.  This is
  61      * most often in shared libraries or in libraries linked to a C program.
  62      *
  63      * Params:
  64      *  dg = A delegate which will receive any exception thrown during the
  65      *       termination process or null if such exceptions should be
  66      *       discarded.
  67      *
  68      * Returns:
  69      *  true if termination succeeds and false if termination fails.
  70      */
  71     static bool terminate( void delegate( Exception ) dg = null )
  72     {
  73         return rt_term( dg );
  74     }
  75
  76
  77     /**
  78      * Returns true if the runtime is halting.  Under normal circumstances,
  79      * this will be set between the time that normal application code has
  80      * exited and before module dtors are called.
  81      *
  82      * Returns:
  83      *  true if the runtime is halting.
  84      */
  85     static bool isHalting()
  86     {
  87         return rt_isHalting();
  88     }
  89
  90
  91     /**
  92      * Overrides the default trace mechanism with s user-supplied version.  A
  93      * trace represents the context from which an exception was thrown, and the
  94      * trace handler will be called when this occurs.  The pointer supplied to
  95      * this routine indicates the base address from which tracing should occur.
  96      * If the supplied pointer is null then the trace routine should determine
  97      * an appropriate calling context from which to begin the trace.
  98      *
  99      * Params:
 100      *  h = The new trace handler.  Set to null to use the default handler.
 101      */
 102     static void traceHandler( TraceHandler h )
 103     {
 104         rt_setTraceHandler( h );
 105     }
 106
 107
 108     /**
 109      * Overrides the default collect hander with a user-supplied version.  This
 110      * routine will be called for each resource object that is finalized in a
 111      * non-deterministic manner--typically during a garbage collection cycle.
 112      * If the supplied routine returns true then the object's dtor will called
 113      * as normal, but if the routine returns false than the dtor will not be
 114      * called.  The default behavior is for all object dtors to be called.
 115      *
 116      * Params:
 117      *  h = The new collect handler.  Set to null to use the default handler.
 118      */
 119     static void collectHandler( CollectHandler h )
 120     {
 121         rt_setCollectHandler( h );
 122     }
 123
 124
 125     /**
 126      * Overrides the default module unit tester with a user-supplied version.
 127      * This routine will be called once on program initialization.  The return
 128      * value of this routine indicates to the runtime whether the body of the
 129      * program will be executed.
 130      *
 131      * Params:
 132      *  h = The new unit tester.  Set to null to use the default unit tester.
 133      */
 134     static void moduleUnitTester( ModuleUnitTester h )
 135     {
 136         sm_moduleUnitTester = h;
 137     }
 138
 139
 140 private:
 141     static ModuleUnitTester sm_moduleUnitTester = null;
 142 }
 143
 144
 145 ///////////////////////////////////////////////////////////////////////////////
 146 // Overridable Callbacks
 147 ///////////////////////////////////////////////////////////////////////////////
 148
 149
 150 /**
 151  * This routine is called by the runtime to run module unit tests on startup.
 152  * The user-supplied unit tester will be called if one has been supplied,
 153  * otherwise all unit tests will be run in sequence.
 154  *
 155  * Returns:
 156  *  true if execution should continue after testing is complete and false if
 157  *  not.  Default behavior is to return true.
 158  */
 159 extern (C) bool runModuleUnitTests()
 160 {
 161     if( Runtime.sm_moduleUnitTester is null )
 162     {
 163         foreach( m; ModuleInfo )
 164         {
 165             if( m.unitTest )
 166                 m.unitTest();
 167         }
 168         return true;
 169     }
 170     return Runtime.sm_moduleUnitTester();
 171 }