Модуль 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 со строкой результата, если может преобразовать исключение. Исключения, поднимаемые принтером, игнорируются.

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

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

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

Тип 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.