Модуль Marshal

module Marshal: sig .. end

Маршализация структур данных.

Этот модуль предоставляет функции для кодирования произвольных структур данных как последовательностей байтов, которые затем могут быть записаны в файл или отправлены по каналу или сетевому соединению. Байт-последовательности можно прочитать обратно позже, возможно, в другом процессе, и декодировать обратно в структуру данных. Формат байтовых последовательностей совместим на всех машинах для данной версии OCaml.

Предупреждение: маршализация в настоящее время не является типобезопасной. Тип маршализованных данных не передаётся вместе со значением данных, что делает невозможным проверить, что считанные данные обладают типом, ожидаемым контекстом. В частности, тип результата функций Marshal.from_* задаётся как 'a, но это вводящее в заблуждение: возвращаемое значение OCaml не обладает типом 'a для всех 'a; оно имеет единственный, уникальный тип, который нельзя определить во время компиляции. Программист должен явно указать ожидаемый тип возвращаемого значения, используя следующий синтаксис:

(Marshal.from_channel chan : type). Любое может произойти во время выполнения, если объект в файле не принадлежит заданному типу.

Значения расширяемых вариантов типов, например, исключения (типа exn), возвращаемые размаршализатором, не должны обрабатываться с помощью шаблонов match ... with или try ... with, так как размаршализация не сохраняет информацию, необходимую для сопоставления их конструкторов. Также не работают структурные равенства с другими расширяемыми значениями вариантов. Большинство других применений, таких как Printexc.to_string, всё равно будут работать как ожидается.

Представление маршализованных значений нечитаемо для человека и использует байты, которые не являются печатными символами. Поэтому каналы ввода-вывода, используемые совместно с Marshal.to_channel и Marshal.from_channel должны открываться в двоичном режиме, используя, например, open_out_bin или open_in_bin; каналы, открытые в текстовом режиме, приведут к ошибкам размаршализации на платформах, где текстовые каналы ведут себя иначе, чем двоичные каналы, например, Windows.

type extern_flags =

`\|`	`No_sharing`	`(*`	Не сохранять совместное использование	`*)`
`\|`	`Closures`	`(*`	Отправлять функции-замыкания	`*)`
`\|`	`Compat_32`	`(*`	Обеспечить совместимость с 32-битными системами	`*)`

Флаги для функций Marshal.to_* ниже.

val to_channel : out_channel -> 'a -> extern_flags list -> unit

Marshal.to_channel chan v flags записывает представление v в канал chan. Аргумент flags — это, возможно, пустой список флагов, который управляет поведением маршализации в отношении совместного использования, функциональных значений и совместимости между 32- и 64-битными платформами.

Если flags не содержит Marshal.No_sharing, цикличности и совместное использование внутри значения v обнаруживаются и сохраняются в последовательности байтов. В частности, это гарантирует, что маршализация всегда завершается. Однако совместное использование между значениями, маршализованными последовательными вызовами Marshal.to_channel, не обнаруживается и не сохраняется. Если flags содержит Marshal.No_sharing, совместное использование игнорируется. Это приводит к более быстрому маршализации, если v не содержит общих подструктур, но может привести к более медленной маршализации и более крупным представлениям байтов, если v фактически содержит совместное использование, или даже к зависанию, если v содержит циклы.

Если flags не содержит Marshal.Closures, маршализация завершается ошибкой, когда встречает функциональное значение внутри v: только «чистые» структуры данных, не содержащие функций или объектов, могут безопасно передаваться между различными программами. Если flags содержит Marshal.Closures, функциональные значения будут маршализованы как позиция в коде программы вместе со значениями, соответствующими свободным переменным, захваченным в замыкании. В этом случае вывод маршализации можно считать только в процессах, которые запускают точно ту же программу с точно таким же скомпилированным кодом. (Это проверяется во время размаршализации с помощью хеша MD5 кода, переданного вместе с позицией кода.)

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

Если flags содержит Marshal.Compat_32, маршализация завершается ошибкой, когда встречает целое число, выходящее за диапазон [-2{^30}, 2{^30}-1] целых чисел, представимых на 32-битной платформе. Это гарантирует, что маршализованные данные, сгенерированные на 64-битной платформе, можно безопасно считать на 32-битной платформе. Если flags не содержит Marshal.Compat_32, целые значения за пределами диапазона [-2{^30}, 2{^30}-1] маршализуются и могут быть считаны на 64-битной платформе, но вызовут ошибку во время размаршализации при чтении на 32-битной платформе. Флаг Mashal.Compat_32 имеет значение только при маршализации на 64-битной платформе; он не имеет эффекта, если маршализация выполняется на 32-битной платформе.

Возбуждает Failure если chan не в двоичном режиме.

val to_bytes : 'a -> extern_flags list -> bytes

Marshal.to_bytes v flags возвращает последовательность байтов, содержащую представление v. Аргумент flags имеет то же значение, что и для Marshal.to_channel.

С 4.02.0

val to_string : 'a -> extern_flags list -> string

То же, что и to_bytes, но возвращает результат в виде строки вместо последовательности байтов.

val to_buffer : bytes -> int -> int -> 'a -> extern_flags list -> int

Marshal.to_buffer buff ofs len v flags маршализует значение v, сохраняя его байтовое представление в последовательности buff, начиная с индекса ofs, и записывая не более len байтов. Возвращает количество байтов, фактически записанных в последовательность. Если байтовое представление v не помещается в len символах, возбуждается исключение Failure.

val from_channel : in_channel -> 'a

Marshal.from_channel chan считывает из канала chan байтовое представление структурированного значения, созданного одной из функций Marshal.to_*, и восстанавливает и возвращает соответствующее значение.

Возбуждает
- End_of_file если chan уже находится в конце файла.
- Failure если в конце файла достигнут во время размаршализации или если chan не в двоичном режиме.

val from_bytes : bytes -> int -> 'a

Marshal.from_bytes buff ofs размаршализует структурированное значение, как и Marshal.from_channel, за исключением того, что байтовое представление считывается не из канала, а из последовательности байтов buff, начиная с позиции ofs. Последовательность байтов не изменяется.

С 4.02.0

val from_string : string -> int -> 'a

То же, что и from_bytes, но принимает строку в качестве аргумента вместо последовательности байтов.

val header_size : int

Байты, представляющие маршализованное значение, состоят из заголовка фиксированной длины и переменной части данных, размер которой можно определить из заголовка. Marshal.header_size — размер заголовка в байтах. Marshal.data_size buff ofs — размер части данных в байтах, предполагая, что в buff с позиции ofs хранится допустимый заголовок. Наконец, Marshal.total_size buff ofs — это общий размер маршализованного значения в байтах. И Marshal.data_size, и Marshal.total_size возбуждают Failure если buff, ofs не содержат допустимого заголовка.

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

val data_size : bytes -> int -> int

См. Marshal.header_size.

val total_size : bytes -> int -> int

См. Marshal.header_size.