Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Forums
  - IRC
  - Wiki
  - GitHub
  - Issues
  - Foundation
  - Donate
- Resources
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
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.
License:
Boost License 1.0
Authors:
Sean Kelly

Source: core/runtime.d

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);

Copyright Sean Kelly 2005 - 2009. | Page generated by Ddoc on Sun Jan 22 15:47:30 2017