2 * The runtime module exposes information specific to the D runtime code.
4 * Copyright: Copyright Sean Kelly 2005 - 2009.
5 * License: $(LINK2 http://www.boost.org/LICENSE_1_0.txt, Boost License 1.0)
7 * Source: $(LINK2 https://github.com/dlang/druntime/blob/master/src/core/runtime.d, _runtime.d)
8 * Documentation: https://dlang.org/phobos/core_runtime.html
11 /* NOTE: This file has been patched from the original DMD distribution to
12 * work with the GDC compiler.
22 else version (WatchOS
)
28 // This shouldn't be necessary but ensure that code doesn't get mixed
29 // It does however prevent the unittest SEGV handler to be installed,
30 // which is desireable as it uses backtrace directly.
31 private enum hasExecinfo
= false;
33 else version (DRuntime_Use_Libunwind
)
35 import core
.internal
.backtrace
.libunwind
;
36 // This shouldn't be necessary but ensure that code doesn't get mixed
37 // It does however prevent the unittest SEGV handler to be installed,
38 // which is desireable as it uses backtrace directly.
39 private enum hasExecinfo
= false;
42 import core
.internal
.execinfo
;
44 /// C interface for Runtime.loadLibrary
45 extern (C
) void* rt_loadLibrary(const char* name
);
47 version (Windows
) extern (C
) void* rt_loadLibraryW(const wchar* name
);
49 /// C interface for Runtime.unloadLibrary, returns 1/0 instead of bool
50 extern (C
) int rt_unloadLibrary(void* ptr
);
52 /// C interface for Runtime.initialize, returns 1/0 instead of bool
53 extern(C
) int rt_init();
54 /// C interface for Runtime.terminate, returns 1/0 instead of bool
55 extern(C
) int rt_term();
58 * This type is returned by the module unit test handler to indicate testing
64 * Number of modules which were tested
69 * Number of modules passed the unittests
74 * Should the main function be run or not? This is ignored if any tests
80 * Should we print a summary of the results?
85 * Simple check for whether execution should continue after unit tests
86 * have been run. Works with legacy code that expected a bool return.
89 * true if execution should continue after testing is complete, false if
92 bool opCast(T
: bool)() const
94 return runMain
&& (executed
== passed
);
97 /// Simple return code that says unit tests pass, and main should be run
98 enum UnitTestResult pass
= UnitTestResult(0, 0, true, false);
99 /// Simple return code that says unit tests failed.
100 enum UnitTestResult fail
= UnitTestResult(1, 0, false, false);
103 /// Legacy module unit test handler
104 alias bool function() ModuleUnitTester
;
105 /// Module unit test handler
106 alias UnitTestResult
function() ExtendedModuleUnitTester
;
109 alias bool function(Object
) CollectHandler
;
110 alias Throwable
.TraceInfo
function( void* ptr
) TraceHandler
;
112 alias void delegate( Throwable
) ExceptionHandler
;
113 extern (C
) void _d_print_throwable(Throwable t
);
115 extern (C
) void* thread_stackBottom();
121 // NOTE: Some module ctors will run before this handler is set, so it's
122 // still possible the app could exit without a stack trace. If
123 // this becomes an issue, the handler could be set in C main
124 // before the module ctors are run.
125 Runtime
.traceHandler
= &defaultTraceHandler
;
129 ///////////////////////////////////////////////////////////////////////////////
131 ///////////////////////////////////////////////////////////////////////////////
134 * Stores the unprocessed arguments supplied when the
135 * process was started.
139 int argc
; /// The argument count.
140 char** argv
; /// The arguments as a C array of strings.
144 * This struct encapsulates all functionality related to the underlying runtime
145 * module for the calling context.
150 * Initializes the runtime. This call is to be used in instances where the
151 * standard program initialization process is not executed. This is most
152 * often in shared libraries or in libraries linked to a C program.
153 * If the runtime was already successfully initialized this returns true.
154 * Each call to initialize must be paired by a call to $(LREF terminate).
157 * true if initialization succeeded or false if initialization failed.
159 static bool initialize()
165 * Terminates the runtime. This call is to be used in instances where the
166 * standard program termination process will not be not executed. This is
167 * most often in shared libraries or in libraries linked to a C program.
168 * If the runtime was not successfully initialized the function returns false.
171 * true if termination succeeded or false if termination failed.
173 static bool terminate()
179 * Returns the arguments supplied when the process was started.
182 * The arguments supplied when this process was started.
184 extern(C
) pragma(mangle
, "rt_args") static @property string
[] args();
187 * Returns the unprocessed C arguments supplied when the process was started.
188 * Use this when you need to supply argc and argv to C libraries.
191 * A $(LREF CArgs) struct with the arguments supplied when this process was started.
195 * import core.runtime;
197 * // A C library function requiring char** arguments
198 * extern(C) void initLibFoo(int argc, char** argv);
202 * auto args = Runtime.cArgs;
203 * initLibFoo(args.argc, args.argv);
207 extern(C
) pragma(mangle
, "rt_cArgs") static @property CArgs
cArgs() @nogc;
210 * Locates a dynamic library with the supplied library name and dynamically
211 * loads it into the caller's address space. If the library contains a D
212 * runtime it will be integrated with the current runtime.
215 * name = The name of the dynamic library to load.
218 * A reference to the library or null on error.
220 static void* loadLibrary()(const scope char[] name
)
222 import core
.stdc
.stdlib
: free
, malloc
;
225 import core
.sys
.windows
.winnls
: CP_UTF8
, MultiByteToWideChar
;
226 import core
.sys
.windows
.winnt
: WCHAR
;
228 if (name
.length
== 0) return null;
229 // Load a DLL at runtime
230 auto len
= MultiByteToWideChar(
231 CP_UTF8
, 0, name
.ptr
, cast(int)name
.length
, null, 0);
235 auto buf
= cast(WCHAR
*)malloc((len
+1) * WCHAR
.sizeof
);
236 if (buf
is null) return null;
237 scope (exit
) free(buf
);
239 len
= MultiByteToWideChar(
240 CP_UTF8
, 0, name
.ptr
, cast(int)name
.length
, buf
, len
);
246 return rt_loadLibraryW(buf
);
250 /* Need a 0-terminated C string for the dll name
252 immutable len
= name
.length
;
253 auto buf
= cast(char*)malloc(len
+ 1);
254 if (!buf
) return null;
255 scope (exit
) free(buf
);
257 buf
[0 .. len
] = name
[];
260 return rt_loadLibrary(buf
);
266 * Unloads the dynamic library referenced by p. If this library contains a
267 * D runtime then any necessary finalization or cleanup of that runtime
271 * p = A reference to the library to unload.
273 static bool unloadLibrary()(void* p
)
275 return !!rt_unloadLibrary(p
);
280 * Overrides the default trace mechanism with a user-supplied version. A
281 * trace represents the context from which an exception was thrown, and the
282 * trace handler will be called when this occurs. The pointer supplied to
283 * this routine indicates the base address from which tracing should occur.
284 * If the supplied pointer is null then the trace routine should determine
285 * an appropriate calling context from which to begin the trace.
288 * h = The new trace handler. Set to null to use the default handler.
290 extern(C
) pragma(mangle
, "rt_setTraceHandler") static @property void traceHandler(TraceHandler h
);
293 * Gets the current trace handler.
296 * The current trace handler or null if none has been set.
298 extern(C
) pragma(mangle
, "rt_getTraceHandler") static @property TraceHandler
traceHandler();
301 * Overrides the default collect hander with a user-supplied version. This
302 * routine will be called for each resource object that is finalized in a
303 * non-deterministic manner--typically during a garbage collection cycle.
304 * If the supplied routine returns true then the object's dtor will called
305 * as normal, but if the routine returns false than the dtor will not be
306 * called. The default behavior is for all object dtors to be called.
309 * h = The new collect handler. Set to null to use the default handler.
311 extern(C
) pragma(mangle
, "rt_setCollectHandler") static @property void collectHandler( CollectHandler h
);
315 * Gets the current collect handler.
318 * The current collect handler or null if none has been set.
320 extern(C
) pragma(mangle
, "rt_getCollectHandler") static @property CollectHandler
collectHandler();
324 * Overrides the default module unit tester with a user-supplied version.
325 * This routine will be called once on program initialization. The return
326 * value of this routine indicates to the runtime whether the tests ran
329 * There are two options for handlers. The `bool` version is deprecated but
330 * will be kept for legacy support. Returning `true` from the handler is
331 * equivalent to returning `UnitTestResult.pass` from the extended version.
332 * Returning `false` from the handler is equivalent to returning
333 * `UnitTestResult.fail` from the extended version.
335 * See the documentation for `UnitTestResult` to see how you should set up
336 * the return structure.
338 * See the documentation for `runModuleUnitTests` for how the default
339 * algorithm works, or read the example below.
342 * h = The new unit tester. Set both to null to use the default unit
347 * shared static this()
349 * import core.runtime;
351 * Runtime.extendedModuleUnitTester = &customModuleUnitTester;
354 * UnitTestResult customModuleUnitTester()
358 * writeln("Using customModuleUnitTester");
360 * // Do the same thing as the default moduleUnitTester:
361 * UnitTestResult result;
362 * foreach (m; ModuleInfo)
366 * auto fp = m.unitTest;
376 * catch (Throwable e)
383 * if (result.executed != result.passed)
385 * result.runMain = false; // don't run main
386 * result.summarize = true; // print failure
390 * result.runMain = true; // all UT passed
391 * result.summarize = false; // be quiet about it.
397 static @property void extendedModuleUnitTester( ExtendedModuleUnitTester h
)
399 sm_extModuleUnitTester
= h
;
403 static @property void moduleUnitTester( ModuleUnitTester h
)
405 sm_moduleUnitTester
= h
;
409 * Gets the current legacy module unit tester.
411 * This property should not be used, but is supported for legacy purposes.
413 * Note that if the extended unit test handler is set, this handler will
417 * The current legacy module unit tester handler or null if none has been
420 static @property ModuleUnitTester
moduleUnitTester()
422 return sm_moduleUnitTester
;
426 * Gets the current module unit tester.
428 * This handler overrides any legacy module unit tester set by the
429 * moduleUnitTester property.
432 * The current module unit tester handler or null if none has been
435 static @property ExtendedModuleUnitTester
extendedModuleUnitTester()
437 return sm_extModuleUnitTester
;
442 // NOTE: This field will only ever be set in a static ctor and should
443 // never occur within any but the main thread, so it is safe to
444 // make it __gshared.
445 __gshared ExtendedModuleUnitTester sm_extModuleUnitTester
= null;
446 __gshared ModuleUnitTester sm_moduleUnitTester
= null;
450 * Set source file path for coverage reports.
453 * path = The new path name.
455 * This is a dmd specific setting.
457 extern (C
) void dmd_coverSourcePath(string path
);
460 * Set output path for coverage reports.
463 * path = The new path name.
465 * This is a dmd specific setting.
467 extern (C
) void dmd_coverDestPath(string path
);
470 * Enable merging of coverage reports with existing data.
473 * flag = enable/disable coverage merge mode
475 * This is a dmd specific setting.
477 extern (C
) void dmd_coverSetMerge(bool flag
);
480 * Set the output file name for profile reports (-profile switch).
481 * An empty name will set the output to stdout.
486 * This is a dmd specific setting.
488 extern (C
) void trace_setlogfilename(string name
);
491 * Set the output file name for the optimized profile linker DEF file (-profile switch).
492 * An empty name will set the output to stdout.
497 * This is a dmd specific setting.
499 extern (C
) void trace_setdeffilename(string name
);
502 * Set the output file name for memory profile reports (-profile=gc switch).
503 * An empty name will set the output to stdout.
508 * This is a dmd specific setting.
510 extern (C
) void profilegc_setlogfilename(string name
);
512 ///////////////////////////////////////////////////////////////////////////////
513 // Overridable Callbacks
514 ///////////////////////////////////////////////////////////////////////////////
518 * This routine is called by the runtime to run module unit tests on startup.
519 * The user-supplied unit tester will be called if one has been set,
520 * otherwise all unit tests will be run in sequence.
522 * If the extended unittest handler is registered, this function returns the
523 * result from that handler directly.
525 * If a legacy boolean returning custom handler is used, `false` maps to
526 * `UnitTestResult.fail`, and `true` maps to `UnitTestResult.pass`. This was
527 * the original behavior of the unit testing system.
529 * If no unittest custom handlers are registered, the following algorithm is
530 * executed (the behavior can be affected by the `--DRT-testmode` switch
532 * 1. Execute any unittests present. For each that fails, print the stack
533 * trace and continue.
534 * 2. If no unittests were present, set summarize to false, and runMain to
536 * 3. Otherwise, set summarize to true, and runMain to false.
538 * See the documentation for `UnitTestResult` for details on how the runtime
539 * treats the return value from this function.
541 * If the switch `--DRT-testmode` is passed to the executable, it can have
543 * 1. "run-main": even if unit tests are run (and all pass), runMain is set
545 * 2. "test-or-main": any unit tests present will cause the program to
546 * summarize the results and exit regardless of the result. This is the
548 * 3. "test-only", runMain is set to false, even with no tests present.
550 * This command-line parameter does not affect custom unit test handlers.
553 * A `UnitTestResult` struct indicating the result of running unit tests.
555 extern (C
) UnitTestResult
runModuleUnitTests()
558 import core
.sys
.windows
.stacktrace
;
560 static if (__traits(compiles
, new LibBacktrace(0)))
562 import core
.sys
.posix
.signal
; // segv handler
564 static extern (C
) void unittestSegvHandler(int signum
, siginfo_t
* info
, void* ptr
)
566 import core
.stdc
.stdio
;
567 fprintf(stderr
, "Segmentation fault while running unittests:\n");
568 fprintf(stderr
, "----------------\n");
570 // First frame is LibBacktrace ctor. Second is signal handler,
571 // but include that for now
572 scope bt = new LibBacktrace(1);
574 foreach (size_t i
, const(char[]) msg
; bt)
575 fprintf(stderr
, "%s\n", msg
.ptr ? msg
.ptr
: "???");
578 sigaction_t action
= void;
579 sigaction_t oldseg
= void;
580 sigaction_t oldbus
= void;
582 (cast(byte*) &action
)[0 .. action
.sizeof
] = 0;
583 sigfillset(&action
.sa_mask
); // block other signals
584 action
.sa_flags
= SA_SIGINFO | SA_RESETHAND
;
585 action
.sa_sigaction
= &unittestSegvHandler
;
586 sigaction(SIGSEGV
, &action
, &oldseg
);
587 sigaction(SIGBUS
, &action
, &oldbus
);
590 sigaction(SIGSEGV
, &oldseg
, null);
591 sigaction(SIGBUS
, &oldbus
, null);
594 else static if (hasExecinfo
)
596 import core
.sys
.posix
.signal
; // segv handler
598 static extern (C
) void unittestSegvHandler( int signum
, siginfo_t
* info
, void* ptr
) nothrow
600 static enum MAXFRAMES
= 128;
601 void*[MAXFRAMES
] callstack
;
603 auto numframes
= backtrace( callstack
.ptr
, MAXFRAMES
);
604 backtrace_symbols_fd( callstack
.ptr
, numframes
, 2 );
607 sigaction_t action
= void;
608 sigaction_t oldseg
= void;
609 sigaction_t oldbus
= void;
611 (cast(byte*) &action
)[0 .. action
.sizeof
] = 0;
612 sigfillset( &action
.sa_mask
); // block other signals
613 action
.sa_flags
= SA_SIGINFO | SA_RESETHAND
;
614 action
.sa_sigaction
= &unittestSegvHandler
;
615 sigaction( SIGSEGV
, &action
, &oldseg
);
616 sigaction( SIGBUS
, &action
, &oldbus
);
619 sigaction( SIGSEGV
, &oldseg
, null );
620 sigaction( SIGBUS
, &oldbus
, null );
624 if (Runtime
.sm_extModuleUnitTester
!is null)
625 return Runtime
.sm_extModuleUnitTester();
626 else if (Runtime
.sm_moduleUnitTester
!is null)
627 return Runtime
.sm_moduleUnitTester() ? UnitTestResult
.pass
: UnitTestResult
.fail
;
628 UnitTestResult results
;
629 foreach ( m
; ModuleInfo
)
633 auto fp
= m
.unitTest
;
637 import core
.exception
;
644 catch ( Throwable e
)
646 if ( typeid(e
) == typeid(AssertError
) )
648 // Crude heuristic to figure whether the assertion originates in
649 // the unittested module. TODO: improve.
650 auto moduleName
= m
.name
;
651 if (moduleName
.length
&& e
.file
.length
> moduleName
.length
652 && e
.file
[0 .. moduleName
.length
] == moduleName
)
654 import core
.stdc
.stdio
;
655 printf("%.*s(%llu): [unittest] %.*s\n",
656 cast(int) e
.file
.length
, e
.file
.ptr
, cast(ulong) e
.line
,
657 cast(int) e
.message
.length
, e
.message
.ptr
);
659 // Exception originates in the same module, don't print
661 // TODO: omit stack trace only if assert was thrown
662 // directly by the unittest.
666 // TODO: perhaps indent all of this stuff.
667 _d_print_throwable(e
);
671 import core
.internal
.parseoptions
: rt_configOption
;
673 if (results
.passed
!= results
.executed
)
675 // by default, we always print a summary if there are failures.
676 results
.summarize
= true;
678 else switch (rt_configOption("testmode", null, false))
681 results
.runMain
= true;
684 // Never run main, always summarize
685 results
.summarize
= true;
688 // By default, do not run main if tests are present.
690 // only run main if there were no tests. Only summarize if we are not
692 results
.runMain
= (results
.executed
== 0);
693 results
.summarize
= !results
.runMain
;
696 assert(0, "Unknown --DRT-testmode option: " ~ rt_configOption("testmode", null, false));
703 * Get the default `Throwable.TraceInfo` implementation for the platform
705 * This functions returns a trace handler, allowing to inspect the
706 * current stack trace.
709 * ptr = (Windows only) The context to get the stack trace from.
710 * When `null` (the default), start from the current frame.
713 * A `Throwable.TraceInfo` implementation suitable to iterate over the stack,
714 * or `null`. If called from a finalizer (destructor), always returns `null`
715 * as trace handlers allocate.
717 Throwable
.TraceInfo
defaultTraceHandler( void* ptr
= null )
719 // avoid recursive GC calls in finalizer, trace handlers should be made @nogc instead
720 import core
.memory
: GC
;
724 static if (__traits(compiles
, new LibBacktrace(0)))
727 static enum FIRSTFRAME
= 4;
729 static enum FIRSTFRAME
= 4;
731 static enum FIRSTFRAME
= 0;
732 return new LibBacktrace(FIRSTFRAME
);
734 else static if (__traits(compiles
, new UnwindBacktrace(0)))
737 static enum FIRSTFRAME
= 5;
739 static enum FIRSTFRAME
= 4;
741 static enum FIRSTFRAME
= 0;
742 return new UnwindBacktrace(FIRSTFRAME
);
744 else version (Windows
)
746 import core
.sys
.windows
.stacktrace
;
747 static if (__traits(compiles
, new StackTrace(0, null)))
749 import core
.sys
.windows
.winnt
: CONTEXT
;
754 return new StackTrace(FIRSTFRAME
, cast(CONTEXT
*)ptr
);
759 else static if (__traits(compiles
, new DefaultTraceInfo()))
760 return new DefaultTraceInfo();
765 /// Example of a simple program printing its stack trace
769 import core
.stdc
.stdio
;
773 auto trace
= defaultTraceHandler(null);
774 foreach (line
; trace
)
776 printf("%.*s\n", cast(int)line
.length
, line
.ptr
);
781 version (DRuntime_Use_Libunwind
)
783 import core
.internal
.backtrace
.handler
;
785 alias DefaultTraceInfo
= LibunwindHandler
;
787 /// Default implementation for most POSIX systems
788 else static if (hasExecinfo
) private class DefaultTraceInfo
: Throwable
.TraceInfo
790 import core
.demangle
;
791 import core
.stdc
.stdlib
: free
;
792 import core
.stdc
.string
: strlen
, memchr
, memmove
;
796 // it may not be 1 but it is good enough to get
797 // in CALL instruction address range for backtrace
798 enum CALL_INSTRUCTION_SIZE
= 1;
800 static if (__traits(compiles
, backtrace((void**).init
, int.init
)))
801 numframes
= backtrace(this.callstack
.ptr
, MAXFRAMES
);
802 // Backtrace succeeded, adjust the frame to point to the caller
804 foreach (ref elem
; this.callstack
)
805 elem
-= CALL_INSTRUCTION_SIZE
;
806 else // backtrace() failed, do it ourselves
808 static void** getBasePtr()
810 version (D_InlineAsm_X86
)
811 asm { naked
; mov EAX
, EBP
; ret; }
813 version (D_InlineAsm_X86_64
)
814 asm { naked
; mov RAX
, RBP
; ret; }
819 auto stackTop
= getBasePtr();
820 auto stackBottom
= cast(void**) thread_stackBottom();
823 if ( stackTop
&& &dummy
< stackTop
&& stackTop
< stackBottom
)
825 auto stackPtr
= stackTop
;
827 for ( numframes
= 0; stackTop
<= stackPtr
&&
828 stackPtr
< stackBottom
&&
829 numframes
< MAXFRAMES
; )
831 callstack
[numframes
++] = *(stackPtr
+ 1) - CALL_INSTRUCTION_SIZE
;
832 stackPtr
= cast(void**) *stackPtr
;
838 override int opApply( scope int delegate(ref const(char[])) dg
) const
840 return opApply( (ref size_t
, ref const(char[]) buf
)
846 override int opApply( scope int delegate(ref size_t
, ref const(char[])) dg
) const
848 version (linux
) enum enableDwarf
= true;
849 else version (FreeBSD
) enum enableDwarf
= true;
850 else version (DragonFlyBSD
) enum enableDwarf
= true;
851 else version (OpenBSD
) enum enableDwarf
= true;
852 else version (Darwin
) enum enableDwarf
= true;
853 else enum enableDwarf
= false;
855 const framelist
= backtrace_symbols( callstack
.ptr
, numframes
);
856 scope(exit
) free(cast(void*) framelist
);
858 static if (enableDwarf
)
860 import core
.internal
.backtrace
.dwarf
;
861 return traceHandlerOpApplyImpl(numframes
,
863 (i
) { auto str = framelist
[i
][0 .. strlen(framelist
[i
])]; return getMangledSymbolName(str); },
869 for (size_t pos
= 0; pos
< numframes
; ++pos
)
871 char[4096] fixbuf
= void;
872 auto buf
= framelist
[pos
][0 .. strlen(framelist
[pos
])];
873 buf
= fixline( buf
, fixbuf
);
874 ret = dg( pos
, buf
);
882 override string
toString() const
885 foreach ( i
, line
; this )
886 buf
~= i ?
"\n" ~ line
: line
;
892 static enum MAXFRAMES
= 128;
893 void*[MAXFRAMES
] callstack
= void;
896 const(char)[] fixline( const(char)[] buf
, return ref char[4096] fixbuf
) const
898 size_t symBeg
, symEnd
;
900 getMangledSymbolName(buf
, symBeg
, symEnd
);
902 enum min
= (size_t a
, size_t b
) => a
<= b ? a
: b
;
903 if (symBeg
== symEnd || symBeg
>= fixbuf
.length
)
905 immutable len
= min(buf
.length
, fixbuf
.length
);
906 fixbuf
[0 .. len
] = buf
[0 .. len
];
907 return fixbuf
[0 .. len
];
911 fixbuf
[0 .. symBeg
] = buf
[0 .. symBeg
];
913 auto sym
= demangle(buf
[symBeg
.. symEnd
], fixbuf
[symBeg
.. $]);
915 if (sym
.ptr
!is fixbuf
.ptr
+ symBeg
)
917 // demangle reallocated the buffer, copy the symbol to fixbuf
918 immutable len
= min(fixbuf
.length
- symBeg
, sym
.length
);
919 memmove(fixbuf
.ptr
+ symBeg
, sym
.ptr
, len
);
920 if (symBeg
+ len
== fixbuf
.length
)
924 immutable pos
= symBeg
+ sym
.length
;
925 assert(pos
< fixbuf
.length
);
926 immutable tail
= buf
.length
- symEnd
;
927 immutable len
= min(fixbuf
.length
- pos
, tail
);
928 fixbuf
[pos
.. pos
+ len
] = buf
[symEnd
.. symEnd
+ len
];
929 return fixbuf
[0 .. pos
+ len
];