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

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

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 являются позициями относительно начала line_number. end_col относится к началу end_line.

Этот тип используется для итерации по слотам в стеке вызовов 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.