Модуль Printexc

Тип значений исключений.

Printexc.to_string e возвращает строковое представление исключения e.

Printexc.to_string_default e возвращает строковое представление исключения e, игнорируя все зарегистрированные принтеры исключений.

Printexc.print fn x применяет fn к x и возвращает результат. Если вычисление fn x вызывает исключение, имя исключения выводится в стандартный поток ошибок, и исключение снова поднимается. Типичное использование — перехватить и сообщить об исключениях, которые возникают при применении функции.

Printexc.catch fn x подобно Printexc.print, но завершает программу с кодом выхода 2 после вывода необработанного исключения. Эта функция устарела: система выполнения теперь способна выводить необработанные исключения так же точно, как и Printexc.catch. Кроме того, вызов Printexc.catch затрудняет отслеживание местоположения исключения с помощью отладчика или средства трассировки стека. Поэтому не используйте Printexc.catch в новом коде.

Printexc.print_backtrace oc выводит трассировку исключения в канал вывода oc. Трассировка показывает места в программе, где возникло и где было распространено последнее возникшее исключение через вызовы функций.

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

Printexc.get_backtrace () возвращает строку, содержащую ту же трассировку исключения, что и Printexc.print_backtrace. Аналогичные ограничения по использованию, как у Printexc.print_backtrace.

Printexc.record_backtrace b включает (если b = true) или выключает (если b = false) запись трассировок исключений. Изначально трассировки не записываются, если флаг b не задан программе через переменную OCAMLRUNPARAM.

Printexc.backtrace_status() возвращает true, если трассировки исключений в настоящее время записываются, false, если нет.

Printexc.register_printer fn регистрирует fn как принтер исключений. Принтер должен возвращать None или поднимать исключение, если он не знает, как преобразовать переданное исключение, и Some
    s со строкой s, если может преобразовать исключение. Исключения, поднятые принтером, игнорируются.

При преобразовании исключения в строку принтеры вызываются в обратном порядке их регистрации, пока принтер не вернёт значение Some s (если такого принтера нет, среда выполнения использует универсальный принтер).

Используя этот механизм, следует учитывать, что трассировка исключения прикреплена к потоку, в котором оно было поднято, а не к самому исключению. Практически это означает, что код, связанный с fn, не должен использовать трассировку, если он сам поднял исключение ранее.

Printexc.use_printers e возвращает None, если нет зарегистрированных принтеров, и Some s со строкой else в противном случае.

Тип raw_backtrace хранит трассировку в низкоуровневом формате, который можно преобразовать в пригодную форму с помощью raw_backtrace_entries и backtrace_slots_of_raw_entry ниже.

Преобразование трассировок в backtrace_slot медленнее, чем захват трассировок. Если приложение обрабатывает много трассировок, может быть полезно использовать raw_backtrace для избежания или отсрочки преобразования.

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

raw_backtrace_entry — элемент raw_backtrace.

Каждый raw_backtrace_entry — это неявное целое число, значение которого не сохраняется между разными программами или даже между различными запусками одной и той же бинарной программы.

raw_backtrace_entry можно преобразовать в пригодную форму, используя backtrace_slots_of_raw_entry ниже. Обратите внимание, что из-за инлайнинга одно raw_backtrace_entry может преобразовываться в несколько backtrace_slot.

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

Снова из-за инлайнинга может быть несколько различных значений raw_backtrace_entry, которые преобразуются в одинаковые backtrace_slot.

Однако, если два raw_backtrace_entry равны как целые числа, то они представляют те же самые backtrace_slot.

Printexc.get_raw_backtrace () возвращает ту же трассировку исключения, что и Printexc.print_backtrace, но в необработанном формате. Аналогичные ограничения по использованию, как у Printexc.print_backtrace.

Вывести необработанную трассировку в том же формате, что и Printexc.print_backtrace.

Возвращает строку из необработанной трассировки в том же формате, что и Printexc.get_backtrace.

Повторно вызовите исключение, используя заданную raw_backtrace в качестве источника исключения.

Printexc.get_callstack n возвращает описание вершины стека вызовов в текущей точке программы (для текущего потока), с максимальным количеством n элементов. (Примечание: эта функция никак не связана с исключениями, несмотря на то, что она входит в модуль Printexc.)

Printexc.default_uncaught_exception_handler выводит исключение и трассировку в стандартный поток ошибок.

Printexc.set_uncaught_exception_handler fn регистрирует fn в качестве обработчика необработанных исключений. По умолчанию используется Printexc.default_uncaught_exception_handler.

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

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

Если fn вызывает исключение, оба исключения, переданные в fn и вызванные fn, будут выведены с соответствующей трассировкой.

Абстрактный тип backtrace_slot представляет собой отдельный слот трассировки.

Возвращает слоты необработанной трассировки или None, если ни один из них не содержит полезной информации.

В возвращаемом массиве слот с индексом 0 соответствует последнему вызову функции, поднятию исключения или примитивному вызову get_backtrace в трассировке.

Возможные причины возврата None следующие:

• ни один из слотов в трассировке не происходит из модулей, скомпилированных с информацией отладки (-g)
• программа — это программа байткода, которая не была связана с включенной информацией отладки (ocamlc -g)

Возвращает слоты одного отдельного элемента необработанной трассировки или None, если этот элемент не содержит информацию об отладке.

Слоты возвращаются в том же порядке, что и backtrace_slots: слот с индексом 0 — это последний вызов, поднятие исключения или примитив, а последующие слоты представляют вызывающие стороны.

Тип информации о местоположении, найденной в стеках вызовов. start_char и end_char представляют позиции относительно начала строки.

Этот тип используется для перебора слотов в стеке вызовов raw_backtrace. Для большинства целей, backtrace_slots_of_raw_entry использовать проще.

Как и raw_backtrace_entry, значения этого типа специфичны для процесса и ни в коем случае не должны передаваться, так как небезопасны в использовании (маршаллинг может не завершиться ошибкой, но размаршаллинг и использование результата приведет к неопределенному поведению).

Элементы этого типа могут сравниваться и хешироваться: если два элемента равны, то они представляют одно и то же местоположение в исходном коде (обратное не всегда верно при наличии встраивания, например).

raw_backtrace_length bckt возвращает количество слотов в стеке вызовов bckt.

get_raw_backtrace_slot bckt pos возвращает слот под позицией pos в стеке вызовов bckt.

Извлекает понятный пользователю backtrace_slot из низкоуровневого raw_backtrace_slot.

get_raw_backtrace_next_slot slot возвращает следующий вложенный слот, если такой есть.

Пример кода для перебора всех фреймов (вложенных и невложенных):

      (* Iterate over inlined frames *)
      let rec iter_raw_backtrace_slot f slot =
        f slot;
        match get_raw_backtrace_next_slot slot with
        | None -> ()
        | Some slot' -> iter_raw_backtrace_slot f slot'

      (* Iterate over stack frames *)
      let iter_raw_backtrace f bt =
        for i = 0 to raw_backtrace_length bt - 1 do
          iter_raw_backtrace_slot f (get_raw_backtrace_slot bt i)
        done
    

Printexc.exn_slot_id возвращает целое число, которое однозначно идентифицирует конструктор, используемый для создания значения исключения exn (в текущей среде выполнения).

Printexc.exn_slot_name exn возвращает внутреннее имя конструктора, используемого для создания значения исключения exn.