core.runtime

Модуль runtime предоставляет информацию, специфичную для кода D-runtime.

Лицензия:

Лицензия Boost 1.0

Авторы:

Шон Келли

Исходный код

runtime.d

Документация

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

void* rt_loadLibrary(const char* name);

Интерфейс C для Runtime.loadLibrary

int rt_unloadLibrary(void* ptr);

Интерфейс C для Runtime.unloadLibrary, возвращает 1/0 вместо bool

int rt_init();

Интерфейс C для Runtime.initialize, возвращает 1/0 вместо bool

int rt_term();

Интерфейс C для Runtime.terminate, возвращает 1/0 вместо bool

struct UnitTestResult;

Этот тип возвращается обработчиком модульных тестов для указания результатов тестирования.

size_t executed;

Количество модулей, которые были протестированы

size_t passed;

Количество модулей, прошедших модульные тесты

bool runMain;

Должна ли выполняться главная функция? Это игнорируется, если какие-либо тесты завершились неудачно.

bool summarize;

Нужно ли печатать сводку результатов?

const bool opCast(T : bool)();

Простая проверка, следует ли продолжать выполнение после запуска модульных тестов. Работает с устаревшим кодом, ожидающим возврата bool.

Возвращает:

true, если выполнение должно продолжаться после завершения тестирования, false — в противном случае.

enum UnitTestResult pass;

Простой код возврата, указывающий, что модульные тесты пройдены, и главная функция должна быть запущена

enum UnitTestResult fail;

Простой код возврата, указывающий, что модульные тесты завершились неудачно.

alias ModuleUnitTester = bool function();

Обработчик устаревших модульных тестов

alias ExtendedModuleUnitTester = UnitTestResult function();

Обработчик модульных тестов

struct CArgs;

Хранит необработанные аргументы, предоставленные при запуске процесса.

int argc;

Количество аргументов.

char** argv;

Аргументы в виде массива C строк.

struct Runtime;

Этот struct объединяет все функции, связанные с базовым модулем выполнения для контекста вызывающего кода.

static bool initialize();

Инициализирует среду выполнения. Этот вызов используется в тех случаях, когда стандартный процесс инициализации программы не выполняется. Это чаще всего встречается в динамических библиотеках или в библиотеках, связанных с программой на C. Если среда выполнения была успешно инициализирована, возвращает true. Каждый вызов initialize должен быть сопряжён с вызовом terminate.

Возвращает:

true, если инициализация прошла успешно, или false, если инициализация завершилась неудачно.

static bool terminate();

Завершает среду выполнения. Этот вызов используется в тех случаях, когда стандартный процесс завершения программы не будет выполнен. Это чаще всего встречается в динамических библиотеках или в библиотеках, связанных с программой на C. Если среда выполнения не была успешно инициализирована, функция возвращает false.

Возвращает:

true, если завершение прошло успешно, или false, если завершение завершилось неудачно.

static @property string[] args();

Возвращает аргументы, предоставленные при запуске процесса.

Возвращает:

Аргументы, предоставленные при запуске этого процесса.

static @nogc @property CArgs cArgs();

Возвращает необработанные аргументы C, предоставленные при запуске процесса. Используйте это, когда вам нужно предоставить argc и argv библиотекам C.

Возвращает:

Структуру CArgs с аргументами, предоставленными при запуске этого процесса.

Пример

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

Находит динамическую библиотеку с заданным именем библиотеки и динамически загружает её в адресное пространство вызывающего кода. Если библиотека содержит D среду выполнения, она будет интегрирована с текущей средой выполнения.

Параметры:

char[] name

Имя динамической библиотеки для загрузки.

Возвращает:

Ссылка на библиотеку или null при ошибке.

bool unloadLibrary()(void* p);

Разгружает динамическую библиотеку, на которую ссылается p. Если эта библиотека содержит D среду выполнения, то будут выполнены все необходимые финализации или очистка этой среды выполнения.

Параметры:

void* p

Ссылка на библиотеку для разгрузки.

static @property void traceHandler(TraceHandler h);

Переопределяет стандартный механизм отслеживания на пользовательскую версию. Отслеживание представляет контекст, из которого было выброшено исключение, и обработчик отслеживания будет вызываться при этом. Указатель, переданный этой процедуре, указывает базовый адрес, с которого должно происходить отслеживание. Если переданный указатель равен null, процедура отслеживания должна определить соответствующий контекст вызова, с которого начать отслеживание.

Параметры:

TraceHandler h

Новый обработчик отслеживания. Установите в null, чтобы использовать обработчик по умолчанию.

static @property TraceHandler traceHandler();

Получает текущий обработчик отслеживания.

Возвращает:

Текущий обработчик отслеживания или null, если он не был установлен.

static @property void collectHandler(CollectHandler h);

Переопределяет стандартный обработчик сбора данных на пользовательскую версию. Эта процедура будет вызвана для каждого объекта ресурса, который завершается непредсказуемым образом — обычно во время цикла сбора мусора. Если предоставленная процедура возвращает true, то dtor объекта будет вызван как обычно, но если процедура возвращает false, то dtor не будет вызван. По умолчанию вызываются все dtor объектов.

Параметры:

CollectHandler h

Новый обработчик сбора. Установите в null, чтобы использовать обработчик по умолчанию.

static @property CollectHandler collectHandler();

Получает текущий обработчик сбора.

Возвращает:

Текущий обработчик сбора или null, если он не был установлен.

static @property void extendedModuleUnitTester(ExtendedModuleUnitTester h);

static @property void moduleUnitTester(ModuleUnitTester h);

Переопределяет стандартный модульный тестер на пользовательскую версию. Эта процедура будет вызвана один раз при инициализации программы. Значение возврата этой процедуры указывает среде выполнения, прошли ли тесты без ошибок.

Доступны два варианта обработчиков. Версия bool устарела, но сохраняется для обратной совместимости. Возврат true от обработчика эквивалентен возврату UnitTestResult.pass от расширенной версии. Возврат false от обработчика эквивалентен возврату UnitTestResult.fail от расширенной версии.

См. документацию для UnitTestResult для того, как правильно настроить структуру возврата.

См. документацию для runModuleUnitTests для того, как работает алгоритм по умолчанию, или прочитайте пример ниже.

Параметры:

ExtendedModuleUnitTester h

Новый модульный тестер. Установите оба в null, чтобы использовать модульный тестер по умолчанию.

Пример

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

Получает текущий устаревший модульный тестер.

Этот свойство не должно использоваться, но поддерживается для обратной совместимости.

Обратите внимание, что если установлен обработчик расширенных модульных тестов, этот обработчик будет проигнорирован.

Возвращает:

Текущий устаревший обработчик модульного тестера или null, если он не был установлен.

static @property ExtendedModuleUnitTester extendedModuleUnitTester();

Получает текущий модульный тестер.

Этот обработчик переопределяет любой устаревший модульный тестер, установленный свойством moduleUnitTester.

Возвращает:

Текущий обработчик модульного тестера или null, если он не был установлен.

void dmd_coverSourcePath(string path);

Устанавливает путь к исходному файлу для отчетов о покрытии кода.

Параметры:

string path

Новое имя пути.

Примечание

Это настройка, специфичная для dmd.

void dmd_coverDestPath(string path);

Устанавливает выходной путь для отчетов о покрытии кода.

Параметры:

string path

Новое имя пути.

Примечание

Это настройка, специфичная для dmd.

void dmd_coverSetMerge(bool flag);

Включить объединение отчётов о покрытии с существующими данными.

Параметры:

bool flag

включить/выключить режим объединения покрытия

Примечание

Это специфическое для dmd значение.

void trace_setlogfilename(string name);

Установить имя выходного файла для отчётов профилирования (-переключатель профиля). Пустое имя установит вывод в стандартный поток вывода.

Параметры:

string name

имя файла

Примечание

Это специфическое для dmd значение.

void trace_setdeffilename(string name);

Установить имя выходного файла для файла DEF оптимизированного профилирующего компоновщика (-переключатель профиля). Пустое имя установит вывод в стандартный поток вывода.

Параметры:

string name

имя файла

Примечание

Это специфическое для dmd значение.

void profilegc_setlogfilename(string name);

Установить имя выходного файла для отчётов профиля памяти (-переключатель профиля=gc). Пустое имя установит вывод в стандартный поток вывода.

Параметры:

string name

имя файла

Примечание

Это специфическое для dmd значение.

UnitTestResult runModuleUnitTests();

Эта процедура вызывается во время выполнения для запуска модульных юнит-тестов при запуске. Пользовательский юнит-тестер будет вызван, если он задан, в противном случае все юнит-тесты будут запущены последовательно.

Если зарегистрирован обработчик расширенных юнит-тестов, эта функция возвращает результат напрямую от этого обработчика.

Если используется традиционный булевый обработчик пользовательского типа, false отображается как UnitTestResult.fail, а true отображается как UnitTestResult.pass. Это было исходным поведением системы юнит-тестирования.

Если нет зарегистрированных пользовательских обработчиков юнит-тестов, выполняется следующий алгоритм (поведение может быть изменено переключателем --DRT-testmode ниже):

1. Выполнить все имеющиеся юнит-тесты. Для каждого не пройденного теста вывести стек вызовов и продолжить.
2. Если юнит-тестов не было, установить summarize в false, и runMain в true.
3. В противном случае, установить summarize в true, и runMain в false.

См. документацию по UnitTestResult для получения подробностей о том, как среда выполнения обрабатывает возвращаемое значение из этой функции.

Если переключатель --DRT-testmode передаётся в исполняемый файл, он может принимать одно из 3 значений:

1. "run-main": даже если юнит-тесты выполняются (и все проходят), runMain устанавливается в true.
2. "test-or-main": любые имеющиеся юнит-тесты заставят программу подвести итоги результатов и выйти независимо от результата. Это значение по умолчанию.
3. "test-only", runMain устанавливается в false, даже если тестов нет.

Этот параметр командной строки не влияет на пользовательские обработчики юнит-тестов.

Возвращает:

Структура UnitTestResult, указывающая результат выполнения юнит-тестов.

Throwable.TraceInfo defaultTraceHandler(void* ptr = null);

Получить реализацию обработчика Throwable.TraceInfo по умолчанию для платформы

Эта функция возвращает обработчик трассировки, позволяющий просмотреть текущий стек вызовов.

Параметры:

void* ptr

(Только Windows) Контекст для получения стека вызовов. Если null (по умолчанию), начать с текущего кадра.

Возвращает:

Реализация обработчика Throwable.TraceInfo для итерации по стеку, или null. Если вызывается из финализатора (деструктора), всегда возвращает null, так как обработчики трассировки выделяют память.

Примеры:

Пример простой программы, выводящей свой стек вызовов

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