Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Downloads
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Forums
  - IRC
  - Community Discord
  - Wiki
  - GitHub
  - Issues
  - Get involved
  - Contributors
  - Foundation
  - Security Team
  - Donate
  - Sponsors
- Resources
  - Tour
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - run.dlang.io
  - 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 runtime.d

Documentation https://dlang.org/phobos/core_runtime.html

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 `UnitTestResult`;
  This type is returned by the module unit test handler to indicate testing results.
  size_t `executed`;
    Number of modules which were tested
  size_t `passed`;
    Number of modules passed the unittests
  bool `runMain`;
    Should the main function be run or not? This is ignored if any tests failed.
  bool `summarize`;
    Should we print a summary of the results?
  const bool `opCast`(T : bool)();
    Simple check for whether execution should continue after unit tests have been run. Works with legacy code that expected a bool return.
    Returns:
    true if execution should continue after testing is complete, false if not.
  enum UnitTestResult `pass`;
    Simple return code that says unit tests pass, and main should be run
  enum UnitTestResult `fail`;
    Simple return code that says unit tests failed.
alias `ModuleUnitTester` = bool function();
  Legacy module unit test handler
alias `ExtendedModuleUnitTester` = UnitTestResult function();
  Module unit test handler
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`()(scope const 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`, Throwable.TraceDeallocator `d` = null);
    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.
    If the deallocator is set, then it is called with the traceinfo when the exception is finalized. The deallocator is only set in the exception if the default handler is used to generate the trace info.
    Parameters:

    TraceHandler `h` | The new trace handler. Set to null to disable exception backtracing.
    Throwable.TraceDeallocator `d` | The new trace deallocator. If non-null, this will be called on exception destruction with the trace info, only when the trace handler is used to generate TraceInfo.

  static @property TraceHandler `traceHandler`();
    Gets the current trace handler.
    Returns:
    The current trace handler or null if none has been set.
  static @property Throwable.TraceDeallocator `traceDeallocator`();
    Gets the current trace deallocator.
    Returns:
    The current trace deallocator 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 `extendedModuleUnitTester`(ExtendedModuleUnitTester `h`);
  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.
    There are two options for handlers. The bool version is deprecated but will be kept for legacy support. Returning true from the handler is equivalent to returning UnitTestResult.pass from the extended version. Returning false from the handler is equivalent to returning UnitTestResult.fail from the extended version.
    See the documentation for UnitTestResult to see how you should set up the return structure.
    See the documentation for runModuleUnitTests for how the default algorithm works, or read the example below.
    Parameters:

    ExtendedModuleUnitTester `h` | The new unit tester. Set both to null to use the default unit tester.

    Example

        shared static this()
        {
            import core.runtime;

            Runtime.extendedModuleUnitTester = &customModuleUnitTester;
        }

        UnitTestResult customModuleUnitTester()
        {
            import std.stdio;

            writeln("Using customModuleUnitTester");

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

                    if (fp)
                    {
                        ++result.executed;
                        try
                        {
                            fp();
                            ++result.passed;
                        }
                        catch (Throwable e)
                        {
                            writeln(e);
                        }
                    }
                }
            }
            if (result.executed != result.passed)
            {
                result.runMain = false;  // don't run main
                result.summarize = true; // print failure
            }
            else
            {
                result.runMain = true;    // all UT passed
                result.summarize = false; // be quiet about it.
            }
            return result;
        }

  static @property ModuleUnitTester `moduleUnitTester`();
    Gets the current legacy module unit tester.
    This property should not be used, but is supported for legacy purposes.
    Note that if the extended unit test handler is set, this handler will be ignored.
    Returns:
    The current legacy module unit tester handler or null if none has been set.
  static @property ExtendedModuleUnitTester `extendedModuleUnitTester`();
    Gets the current module unit tester.
    This handler overrides any legacy module unit tester set by the moduleUnitTester property.
    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.

UnitTestResult `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 set, otherwise all unit tests will be run in sequence.
  If the extended unittest handler is registered, this function returns the result from that handler directly.
  If a legacy boolean returning custom handler is used, false maps to UnitTestResult.fail, and true maps to UnitTestResult.pass. This was the original behavior of the unit testing system.
  If no unittest custom handlers are registered, the following algorithm is executed (the behavior can be affected by the --DRT-testmode switch below):
  1. Execute any unittests present. For each that fails, print the stack trace and continue.
  2. If no unittests were present, set summarize to false, and runMain to true.
  3. Otherwise, set summarize to true, and runMain to false.
  See the documentation for UnitTestResult for details on how the runtime treats the return value from this function.
  If the switch --DRT-testmode is passed to the executable, it can have one of 3 values:
  1. "run-main": even if unit tests are run (and all pass), runMain is set to true.
  2. "test-or-main": any unit tests present will cause the program to summarize the results and exit regardless of the result. This is the default.
  3. "test-only", runMain is set to false, even with no tests present.
  This command-line parameter does not affect custom unit test handlers.
  Returns:
  A UnitTestResult struct indicating the result of running unit tests.
Throwable.TraceInfo `defaultTraceHandler`(void* `ptr` = null);
  Get the default Throwable.TraceInfo implementation for the platform
  This functions returns a trace handler, allowing to inspect the current stack trace.
  IMPORTANT NOTE! the returned trace is potentially not GC allocated, and so you must call defaultTraceDeallocator when you are finished with the TraceInfo
  Parameters:

  void* `ptr` | (Windows only) The context to get the stack trace from. When null (the default), start from the current frame.

  Returns:
  A Throwable.TraceInfo implementation suitable to iterate over the stack, or null. If called from a finalizer (destructor), always returns null as trace handlers allocate.
  Examples:
  Example of a simple program printing its stack trace

      import core.runtime;
      import core.stdc.stdio;

      void main()
      {
          auto trace = defaultTraceHandler(null);
          foreach (line; trace)
          {
              printf("%.*s\n", cast(int)line.length, line.ptr);
          }
          defaultTraceDeallocator(trace);
      }

nothrow void `defaultTraceDeallocator`(Throwable.TraceInfo `info`);
  Deallocate a traceinfo generated by deaultTraceHander.
  Call this function on a TraceInfo generated via defaultTraceHandler when you are done with it. If necessary, this cleans up any manually managed resources from the TraceInfo, and invalidates it. After this, the object is no longer valid.
  Parameters:

  Throwable.TraceInfo `info` | The TraceInfo to deallocate. This should only be a value that was returned by defaultTraceHandler.

Copyright © 1999-2023 by the D Language Foundation | Page generated by Ddoc on Sun Jul 2 00:30:01 2023