Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

core.runtime

The runtime module exposes information specific to the D runtime code.
Authors:
Sean Kelly
void* rt_loadLibrary(const char* name);
C interface for Runtime.loadLibrary
int rt_unloadLibrary(void* ptr);
C interface for Runtime.unloadLibrary, returns 1/0 instead of bool
int rt_init();
C interface for Runtime.initialize, returns 1/0 instead of bool
int rt_term();
C interface for Runtime.terminate, returns 1/0 instead of bool
struct CArgs;
Stores the unprocessed arguments supplied when the process was started.
int argc;
The argument count.
char** argv;
The arguments as a C array of strings.
struct Runtime;
This struct encapsulates all functionality related to the underlying runtime module for the calling context.
static bool initialize();
Initializes the runtime. This call is to be used in instances where the standard program initialization process is not executed. This is most often in shared libraries or in libraries linked to a C program. If the runtime was already successfully initialized this returns true. Each call to initialize must be paired by a call to terminate.
Returns:
true if initialization succeeded or false if initialization failed.
static bool terminate();
Terminates the runtime. This call is to be used in instances where the standard program termination process will not be not executed. This is most often in shared libraries or in libraries linked to a C program. If the runtime was not successfully initialized the function returns false.
Returns:
true if termination succeeded or false if termination failed.
static @property string[] args();
Returns the arguments supplied when the process was started.
Returns:
The arguments supplied when this process was started.
static @nogc @property CArgs cArgs();
Returns the unprocessed C arguments supplied when the process was started. Use this when you need to supply argc and argv to C libraries.
Returns:
A CArgs struct with the arguments supplied when this process was started.

Example:

import core.runtime;

// A C library function requiring char** arguments
extern(C) void initLibFoo(int argc, char** argv);

void main()
{
    auto args = Runtime.cArgs;
    initLibFoo(args.argc, args.argv);
}

void* loadLibrary()(in char[] name);
Locates a dynamic library with the supplied library name and dynamically loads it into the caller's address space. If the library contains a D runtime it will be integrated with the current runtime.
Parameters:
char[] name The name of the dynamic library to load.
Returns:
A reference to the library or null on error.
bool unloadLibrary()(void* p);
Unloads the dynamic library referenced by p. If this library contains a D runtime then any necessary finalization or cleanup of that runtime will be performed.
Parameters:
void* p A reference to the library to unload.
static @property void traceHandler(TraceHandler h);
Overrides the default trace mechanism with a user-supplied version. A trace represents the context from which an exception was thrown, and the trace handler will be called when this occurs. The pointer supplied to this routine indicates the base address from which tracing should occur. If the supplied pointer is null then the trace routine should determine an appropriate calling context from which to begin the trace.
Parameters:
TraceHandler h The new trace handler. Set to null to use the default handler.
static @property TraceHandler traceHandler();
Gets the current trace handler.
Returns:
The current trace handler or null if none has been set.
static @property void collectHandler(CollectHandler h);
Overrides the default collect hander with a user-supplied version. This routine will be called for each resource object that is finalized in a non-deterministic manner--typically during a garbage collection cycle. If the supplied routine returns true then the object's dtor will called as normal, but if the routine returns false than the dtor will not be called. The default behavior is for all object dtors to be called.
Parameters:
CollectHandler h The new collect handler. Set to null to use the default handler.
static @property CollectHandler collectHandler();
Gets the current collect handler.
Returns:
The current collect handler or null if none has been set.
static @property void moduleUnitTester(ModuleUnitTester h);
Overrides the default module unit tester with a user-supplied version. This routine will be called once on program initialization. The return value of this routine indicates to the runtime whether the tests ran without error.
Parameters:
ModuleUnitTester h The new unit tester. Set to null to use the default unit tester.

Example:

version (unittest) shared static this()
{
    import core.runtime;

    Runtime.moduleUnitTester = &customModuleUnitTester;
}

bool customModuleUnitTester()
{
    import std.stdio;

    writeln("Using customModuleUnitTester");

    // Do the same thing as the default moduleUnitTester:
    size_t failed = 0;
    foreach (m; ModuleInfo)
    {
        if (m)
        {
            auto fp = m.unitTest;

            if (fp)
            {
                try
                {
                    fp();
                }
                catch (Throwable e)
                {
                    writeln(e);
                    failed++;
                }
            }
        }
    }
    return failed == 0;
}

static @property ModuleUnitTester moduleUnitTester();
Gets the current module unit tester.
Returns:
The current module unit tester handler or null if none has been set.
void dmd_coverSourcePath(string path);
Set source file path for coverage reports.
Parameters:
string path The new path name.

Note: This is a dmd specific setting.

void dmd_coverDestPath(string path);
Set output path for coverage reports.
Parameters:
string path The new path name.

Note: This is a dmd specific setting.

void dmd_coverSetMerge(bool flag);
Enable merging of coverage reports with existing data.
Parameters:
bool flag enable/disable coverage merge mode

Note: This is a dmd specific setting.

void trace_setlogfilename(string name);
Set the output file name for profile reports (-profile switch). An empty name will set the output to stdout.
Parameters:
string name file name

Note: This is a dmd specific setting.

void trace_setdeffilename(string name);
Set the output file name for the optimized profile linker DEF file (-profile switch). An empty name will set the output to stdout.
Parameters:
string name file name

Note: This is a dmd specific setting.

void profilegc_setlogfilename(string name);
Set the output file name for memory profile reports (-profile=gc switch). An empty name will set the output to stdout.
Parameters:
string name file name

Note: This is a dmd specific setting.

bool runModuleUnitTests();
This routine is called by the runtime to run module unit tests on startup. The user-supplied unit tester will be called if one has been supplied, otherwise all unit tests will be run in sequence.
Returns:
true if execution should continue after testing is complete and false if not. Default behavior is to return true.
Throwable.TraceInfo defaultTraceHandler(void* ptr = null);