Модуль 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 с s результирующей строкой в противном случае.

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

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

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

raw_backtrace_entry — это элемент raw_backtrace.

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

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

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

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.