Глава 15 Система выполнения (ocamlrun)

• 15.1 Обзор
• 15.2 Параметры
• 15.3 Динамическая загрузка общих библиотек
• 15.4 Распространённые ошибки

Команда ocamlrun выполняет файлы байткода, созданные на этапе компоновки командой ocamlc.

15.1 Обзор

Команда ocamlrun состоит из трёх основных частей: интерпретатора байткода, который фактически выполняет файлы байткода; менеджера памяти и сборщика мусора; и набора функций C, которые реализуют примитивные операции, такие как ввод/вывод.

Использование ocamlrun такое:

        ocamlrun options bytecode-executable arg1 ... argn

Первый аргумент, не являющийся параметром, считается именем файла, содержащего исполняемый байткод. (Этот файл ищется в пути к исполняемым файлам, а также в текущем каталоге.) Остальные аргументы передаются программе OCaml в строковом массиве Sys.argv. Элемент 0 этого массива — имя исполняемого файла байткода; элементы от 1 до n — это оставшиеся аргументы arg₁ до arg_n.

Как упоминалось в главе 13, исполняемые файлы байткода, созданные командой ocamlc, являются самодостаточными и умеют автоматически запускать команду ocamlrun на себе. То есть, если a.out — это исполняемый файл байткода,

        a.out arg1 ... argn

работает точно так же, как

        ocamlrun a.out arg1 ... argn

Обратите внимание, что нельзя передавать параметры команде ocamlrun при прямом вызове a.out.

Windows: В некоторых версиях Windows файлы исполняемого байткода являются самодостаточными только в том случае, если их имя оканчивается на .exe. Рекомендуется всегда давать файлам исполняемых байткодов имена, оканчивающиеся на .exe, например, компилируйте с ocamlc -o myprog.exe ..., а не с ocamlc -o myprog ....

15.2 Параметры

Следующие параметры командной строки распознаются командой ocamlrun.

-b

При аварийном завершении программы из-за неперехваченного исключения выводится подробный «стек вызовов» выполнения, показывающий, где было возбуждено исключение и какие вызовы функций были открыты в этот момент. Стек вызовов выводится только если исполняемый файл байткода содержит отладочную информацию, т.е. был скомпилирован и скомпонован с параметром -g для ocamlc. Это эквивалентно установке флага b в переменной окружения OCAMLRUNPARAM (см. ниже).

-config

Вывести номер версии ocamlrun и подробный свод его конфигурации, затем выйти.

-I dir

Добавить каталог dir к стандартному пути поиска динамически загружаемых библиотек (см. раздел 15.3).

-m

Вывести магическое число исполняемого файла байткода и выйти.

-M

Вывести магическое число, ожидаемое для исполняемых файлов байткода данной версией среды выполнения, и выйти.

-p

Вывести имена примитивов, известных этой версией ocamlrun, и выйти.

-t

Увеличивает уровень отслеживания для отладочной среды выполнения (игнорируется в противном случае).

-v

Инструктирует менеджер памяти выводить некоторые сообщения об ошибках в стандартный поток ошибок. Эквивалентно установке v=61 в переменной окружения OCAMLRUNPARAM (см. ниже).

-version

Вывести строку версии и выйти.

-vnum

Вывести короткую строку номера версии и выйти.

Также учитываются следующие переменные среды:

CAML_LD_LIBRARY_PATH

Дополнительные каталоги для поиска динамически загружаемых библиотек (см. раздел 15.3).

OCAMLLIB

Каталог, содержащий стандартную библиотеку OCaml. (Если OCAMLLIB не задан, используется CAMLLIB.) Используется для поиска конфигурационного файла ld.conf для динамической загрузки (см. раздел 15.3). Если не задан, используется каталог библиотеки, указанный при компиляции OCaml.

OCAMLRUNPARAM

Установка параметров выполнения и параметров сборки мусора. (Если OCAMLRUNPARAM не задан, используется CAMLRUNPARAM.) Это переменная должна быть последовательностью спецификаций параметров, разделенных запятыми. Для удобства, запятые в начале переменной игнорируются, а несколько последовательных запятых интерпретируются как одна. Спецификация параметра — это буква опции, за которой следует знак =, десятичное число (или шестнадцатеричное число, начинающееся с 0x), и необязательный множитель. Опции документированы ниже; опции a, i, l, m, M, n, o, O, s, v, w соответствуют полям записи control, документированной в Модуле Gc.

b

(обратная трассировка стека) Вызывает печать обратной трассировки стека при аварийном завершении программы из-за необработанного исключения. Можно указать необязательный аргумент: b=0 отключает печать обратной трассировки стека; b=1 эквивалентно b и включает печать обратной трассировки стека; b=2 включает печать обратной трассировки стека и заставляет систему выполнения загрузить отладочную информацию при запуске программы, а не при печати обратной трассировки. b=2 можно использовать, если система выполнения не может загрузить отладочную информацию при печати обратной трассировки, например, если нет доступных дескрипторов файлов.

c

(cleanup_on_exit) Закрывает систему выполнения корректно при выходе (см. caml_shutdown в разделе 22.7.5). Эта опция также включает пулинг (как в caml_startup_pooled). Этот режим можно использовать для обнаружения утечек с помощью стороннего отладчика памяти.

e

(runtime_events_log_wsize) Размер кольцевых буферов событий времени выполнения в логарифмических степенях двух слов. По умолчанию 16, что даёт буферы размером 64k слов или 512кб на 64-битных системах.

l

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

m

(custom_minor_ratio) Граница для плавающего мусора для памяти вне кучи, занимаемой пользовательскими значениями в меньшей куче. Минорная сборка мусора запускается, когда эта память занимает такую часть памяти меньшей кучи. Выражается в процентах от размера меньшей кучи. По умолчанию: 100. Примечание: это относится только к значениям, выделенным с помощью caml_alloc_custom_mem.

M

(custom_major_ratio) Целевая доля плавающего мусора к размеру основной кучи для памяти вне кучи, занимаемой пользовательскими значениями (например, bigarrays), расположенными в основной куче. Скорость сборки мусора регулируется для использования этой части памяти для мертвых значений, которые ещё не были собраны. Выражается в процентах от размера основной кучи. По умолчанию: 44. Примечание: это относится только к значениям, выделенным с помощью caml_alloc_custom_mem.

n

(custom_minor_max_size) Максимальный объём памяти вне кучи для каждого пользовательского значения, выделенного в меньшей куче. Когда пользовательское значение выделяется в меньшей куче и занимает больше этого объёма байтов, только это значение учитывается в отношении custom_minor_ratio, а остальная часть — напрямую в отношении custom_major_ratio. По умолчанию: 8192 байта. Примечание: это относится только к значениям, выделенным с помощью caml_alloc_custom_mem.

Множитель — это k, M или G для умножения на 2¹⁰, 2²⁰ и 2³⁰ соответственно.

o

(space_overhead) Настройка скорости основной сборки мусора. Подробности см. в документации модуля Gc.

p

(отладка синтаксического анализа) Включение отладочной поддержки для генераторов синтаксического анализа ocamlyacc. При включении этой опции автомат с магазинной памятью, выполняющий синтаксический анализ, печатает трассировку своих действий. Эта опция не принимает аргументов.

R

(рандомизация) Включение по умолчанию рандомизации всех хеш-таблиц (см. Модуль Hashtbl). Эта опция не принимает аргументов.

s

(minor_heap_size) Размер меньшей кучи (в словах).

t

Установка уровня трассировки для отладочного времени выполнения (игнорируется стандартным временем выполнения).

v

(verbose) Сообщения сборщика мусора, которые следует выводить в stderr. Это сумма значений, выбранных из следующего:

1 (= 0x001)

Начало и конец цикла основной сборки мусора.

2 (= 0x002)

Минорная коллекция и фрагмент основной сборки мусора.

4 (= 0x004)

Увеличение и уменьшение кучи.

8 (= 0x008)

Изменение размеров стеков и таблиц менеджера памяти.

16 (= 0x010)

Уплотнение кучи.

32 (= 0x020)

Изменение параметров сборщика мусора.

64 (= 0x040)

Вычисление размера фрагмента основной сборки мусора.

128 (= 0x080)

Вызов функций финализации.

256 (= 0x100)

Сообщения о запуске (загрузка файла исполняемого байт-кода, разрешение общих библиотек).

512 (= 0x200)

Вычисление условия, вызывающего уплотнение.

1024 (= 0x400)

Вывод статистики сборки мусора при завершении программы.

2048 (= 0x800)

Сообщения отладки сборщика мусора.

V

(verify_heap) выполняет проверку целостности кучи сразу после завершения цикла основной сборки мусора

W

Вывод предупреждений времени выполнения в stderr (например, канал открыт для файла, умер без закрытия, невыведенные данные и т.д.)

Если буква опции не распознана, весь параметр игнорируется; если отсутствует знак равенства или число, значение принимается равным 1; если множитель не распознан, он игнорируется.

Например, на 32-битной машине в bash команда

        export OCAMLRUNPARAM='b,s=256k,v=0x015'

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

CAMLRUNPARAM

Если OCAMLRUNPARAM не найден в среде, то используется CAMLRUNPARAM. Если CAMLRUNPARAM также не найден, используются значения по умолчанию.

PATH

Список каталогов, которые проверяются для поиска файла исполняемого байт-кода.

15.3 Динамическая загрузка общих библиотек

На платформах, поддерживающих динамическую загрузку, ocamlrun может динамически подключаться к общим библиотекам C (DLL), предоставляя дополнительные C-примитивы помимо тех, которые предоставляет стандартная система выполнения. Имена этих библиотек предоставляются во время компоновки, как описано в разделе 22.1.4), и записываются в исполняемый байткодовый файл; ocamlrun затем находит эти библиотеки и разрешает ссылки на их примитивы при запуске исполняемой байткодовой программы.

Команда ocamlrun ищет общие библиотеки в следующих каталогах в указанном порядке:

1. Каталоги, указанные в командной строке ocamlrun с опцией -I.
2. Каталоги, указанные в переменной окружения CAML_LD_LIBRARY_PATH.
3. Каталоги, указанные во время компоновки с помощью опции -dllpath для ocamlc. (Эти каталоги записываются в исполняемый байткодовый файл.)
4. Каталоги, указанные в файле ld.conf. Этот файл находится в каталоге стандартной библиотеки OCaml и содержит имена каталогов (по одному на строке), которые нужно искать. Обычно он содержит только одну строку с именем подкаталога stublibs каталога стандартной библиотеки OCaml. Пользователи могут добавить туда имена других каталогов, содержащих часто используемые общие библиотеки; однако, для согласованности установки рекомендуется устанавливать общие библиотеки непосредственно в системный каталог stublibs, а не добавлять строки в файл ld.conf.
5. Каталоги по умолчанию, просматриваемые системным динамическим загрузчиком. В Unix эти каталоги, как правило, включают /lib и /usr/lib, а также каталоги, перечисленные в файле /etc/ld.so.conf и переменной окружения LD_LIBRARY_PATH. В Windows это включает системные каталоги Windows, а также каталоги, перечисленные в переменной окружения PATH.

15.4 Общие ошибки

В этом разделе описаны и объяснены наиболее часто встречающиеся сообщения об ошибках.

filename: no such file or directory

Если filename — это имя исполняемого байткодового файла, это означает, что либо этот файл не существует, либо он не смог запустить интерпретатор байткода ocamlrun на себе. Второй вариант указывает на то, что OCaml не был правильно установлен на вашей системе.

Cannot exec ocamlrun

(При запуске исполняемого байткодового файла.) ocamlrun не был найден в пути к исполняемым файлам. Проверьте, правильно ли установлен OCaml на вашей системе.

Cannot find the bytecode file

Файл, который ocamlrun пытается выполнить (например, файл, указанный как первый аргумент без опций для ocamlrun), либо не существует, либо не является допустимым исполняемым байткодовым файлом.

Truncated bytecode file

Файл, который ocamlrun пытается выполнить, не является допустимым исполняемым байткодовым файлом. Возможно, он был усечён или повреждён после создания. Удалите и перестройте его.

Uncaught exception

Выполняемая программа содержит «свободное» исключение. То есть в какой-то момент она генерирует исключение, и это исключение никогда не обрабатывается. Это приводит к немедленному завершению программы. Название исключения печатается вместе с его строковым, байтовым и целочисленными аргументами (аргументы более сложных типов не печатаются корректно). Для определения контекста необработанного исключения скомпилируйте программу с опцией -g и либо запустите её снова под отладчиком ocamldebug (см. главу 20), либо запустите её с ocamlrun -b или с установленной переменной окружения OCAMLRUNPARAM в значение b=1.

Out of memory

Выполняемой программе требуется больше памяти, чем доступно. Либо программа создаёт чрезмерно большие структуры данных; либо программа содержит слишком много вложенных вызовов функций, и происходит переполнение стека. В некоторых случаях ваша программа абсолютно корректна, просто ей требуется больше памяти, чем предоставляет ваш компьютер. В других случаях сообщение «out of memory» указывает на ошибку в вашей программе: нетерминирующая рекурсивная функция, выделение чрезмерно большого массива, строки или последовательности байтов, попытки создания бесконечного списка или другой структуры данных, …

Чтобы помочь вам диагностировать эту ошибку, запустите программу с опцией -v для ocamlrun или с установленной переменной окружения OCAMLRUNPARAM в значение v=63. Если вы увидите много сообщений «Growing stack…», это, вероятно, циклическая рекурсивная функция. Если вы видите много сообщений «Growing heap…», причём размер кучи медленно увеличивается, это, вероятно, попытка создать структуру данных с слишком большим количеством (бесконечным?) ячеек. Если вы видите несколько сообщений «Growing heap…», но с огромным увеличением размера кучи, это, вероятно, попытка создания чрезмерно большого массива, строки или последовательности байтов.