Внутренние компоненты и структура

Файловый интерфейс

Объект JLDFile имитирует API Base.Dict в максимальной степени. В частности, keys, length, haskey, isempty, get, get! должны работать, как ожидается.

# JLD2.CommittedDatatype — Type

CommittedDatatype

Ссылка на сообщение об общем типе данных (хранящемся где-либо еще в файле). Хранится в группе _types и индексируется.

# JLD2.CustomSerialization — Type

CustomSerialization{T,S}

Дисковое представление данных, которые записываются так, как если бы они имели тип Julia T, но считываются как тип S.

# JLD2.GlobalHeap — Type

GlobalHeap

Представляет структуру глобальной кучи HDF5.

# JLD2.Group — Type

Group(file)

Объект группы JLD2.

Расширенное использование

Принимает два необязательных именованных аргумента: estnumentries::Int=4 estlinkname_len::Int=8 Они определяют, сколько (дополнительного) пустого пространства следует выделить для описания группы (списка записей). Это может быть полезно с точки зрения производительности, если после первоначальной записи в файл в него планируется добавлять много дополнительных наборов данных.

# JLD2.Group — Method

Group(f::JLDFile, name::AbstractString)

Создает пустую группу с именем name на верхнем уровне файла JLDFile f.

# JLD2.Group — Method

Group(g::Group, name::AbstractString)

Создает группу с именем name, которая будет дочерней для группы g.

# JLD2.H5Datatype — Type

H5Datatype

Супертип всех типов данных HDF5.

# JLD2.IndirectPointer — Type

IndirectPointer

При записи данных может потребоваться расширить сопоставление памяти, что сделает недействительными все адреса в памяти, связанные с прежним указателем mmap. IndirectPointer содержит указатель на поле startptr MmapIO и смещение относительно этого указателя. Вычисление адреса в памяти откладывается до преобразования в Ptr{T}, поэтому сопоставление памяти можно расширить с сохранением адресов.

# JLD2.InlineUnionEl — Type

InlineUnionEl{T1,T2}(mask::UInt8, t1::T1, t2::T2)

Пользовательская структура сериализации для двух полей, входящих в битовое объединение, например в других структурах или массивах. Для указания на то, что актуально поле t1, маска принимает значение UInt8(0), а для t2 — UInt8(255).

# JLD2.JLDFile — Type

JLDFile{T<:IO}

Объект файла JLD.

# JLD2.JLDWriteSession — Type

JLDWriteSession{T}

JLDWriteSession отслеживает ссылки на сериализованные объекты. Если T — это словарь, h5offset сопоставляет идентификатор объекта (возвращаемый вызовом objectid) с RelOffset записываемого набора данных. Если это Union{}, ссылки не отслеживаются, а объекты, на которые указывают несколько ссылок, записываются несколько раз.

# JLD2.ReadRepresentation — Type

ReadRepresentation{T,ODR}

Тип, кодирующий как тип Julia T, так и дисковое (HDF5) представление ODR.

# JLD2.RelOffset — Type

RelOffset

Представляет относительное смещение HDF5. Отличается от файлового смещения (используемого в остальных случаях) тем, что задается относительно базового адреса суперблока. fileoffset и h5offset преобразуются между RelOffsets и файловыми смещениями.

# JLD2.SharedDatatype — Type

SharedDatatype

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

# JLD2.TypeMappingException — Type

constructrr(f::JLDFile, T::DataType, dt::CompoundType, attrs::Vector{ReadAttribute}, hard_failure::Bool=false)

Создает ReadRepresentation для указанного типа. Это универсальный метод для всех типов, которые не обрабатываются особым образом ниже.

Если hard_failure имеет значение true, вызывается исключение TypeMappingException вместо попытки воссоздания. Это полезно в случаях, если невозможно узнать, будут ли воссоздаваемые параметрические типы иметь аналогичную структуру в памяти, не проанализировав структуру памяти заранее.

# JLD2.Upgrade — Type

Upgrade(T)

Задает путь обновления для сериализуемых структур с использованием именованного аргумента typemap и rconvert.

# JLD2.behead — Method

behead(T)

Для типа UnionAll рекурсивно устраняет предложения where.

# JLD2.construct_array — Method

construct_array{T}(io::IO, ::Type{T}, ::Val{ndims})

Создает массив путем считывания измерений ndims из io. Предполагается, что в io уже выполнен переход в правильную позицию.

# JLD2.fileoffset — Method

fileoffset(f::JLDFile, x::RelOffset)

Преобразовывает смещение x относительно суперблока файла f в абсолютное смещение.

# JLD2.group_payload_size — Method

group_payload_size(g)

Возвращает размер полезных данных группы, включая сведения о ссылках, сведения о группе и сообщения ссылок, но не заголовок объекта. Предоставляет пространство после сообщения последнего объекта для продолжения сообщения.

# JLD2.h5offset — Method

h5offset(f::JLDFile, x::Integer)

Преобразовывает абсолютное файловое смещение x в смещение относительно суперблока файла f.

# JLD2.jld_finalizer — Method

jld_finalizer(f::JLDFile)

При ликвидации JLDFile объект MmapIO может оказаться несопоставленным в памяти, так как очередность ликвидации в Julia не гарантируется. Это означает, что исходный файл может быть закрыт, прежде чем появится возможность записи в него.

# JLD2.jldopen — Function

jldopen(fname::AbstractString, mode::AbstractString; iotype=MmapIO, compress=false, typemap=Dict())

Открывает файл JLD2 по пути fname.

"r": файл открывается только для чтения; если файл не существует, происходит сбой. "r+": файл открывается для чтения и записи; если файл не существует, происходит сбой. "w"/"w+": файл открывается для чтения и записи; если файл уже существует, он перезаписывается. "a"/"a+": файл открывается для чтения и записи; если файл не существует, создается новый файл. preserving the existing file if one is present

# JLD2.jldsave — Method

jldsave(filename, compress=false; kwargs...)

Создает файл JLD2 по пути filename и сохраняет переменные, переданные в качестве именованных аргументов.

Примеры

jldsave("example.jld2"; a=1, b=2, c)

эквивалентно

jldopen("example.jld2, "w") do f
    f["a"] = 1
    f["b"] = 2
    f["c"] = c
end

Чтобы выбрать тип ввода-вывода IOStream вместо типа по умолчанию MmapIO, используйте jldsave(fn, IOStream; kwargs...).

# JLD2.link_size — Method

link_size(name::String)

Возвращает размер сообщения ссылки, включая заголовок сообщения.

# JLD2.links_size — Method

links_size(pairs)

Возвращает размер нескольких сообщений ссылок. pairs — это итератор пар String => RelOffset.

# JLD2.load_attributes — Method

load_attributes(f::JLDFile, name::AbstractString)
load_attributes(g::Group, name::AbstractString)
load_attributes(f::JLDFile, offset::RelOffset)

Возвращает список атрибутов, назначенных набору данных или группе.

# JLD2.load_datatypes — Method

load_datatypes(f::JLDFile)

Заполняет f.datatypes и f.jlh5types всеми сохраненными типами данных из файла. Это необходимо сделать перед записью, чтобы повторно использовались записанные типы данных.

# JLD2.load_object — Method

load_object(filename)

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

Чтобы загрузить несколько объектов, используйте макрос @load, jldopen или API FileIO.

Пример

Загрузка только одного объекта из JLD2-файла example.jld2:

hello = "world"
save_object("example.jld2", hello)
hello_loaded = load_object("example.jld2")

# JLD2.lookup_offset — Method

lookup_offset(g::Group, name::AbstractString) -> RelOffset

Ищет смещение набора данных в группе. Возвращает UNDEFINED_ADDRESS, если набор данных отсутствует. Не проверяет unwritten_child_groups.

# JLD2.pathize — Method

pathize(g::Group, name::AbstractString, create::Bool) -> Tuple{Group,String}

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

# JLD2.prewrite — Method

prewrite(f::JLDFile)

Проверяет, действительно ли файл JLD доступен для записи, и выдает ошибку, если это нет так. Задает флаг written для файла.

# JLD2.printtoc — Method

printtoc([io::IO,] f::JLDFile [; numlines])

Выводит обзор содержимого файла f в IO.

С помощью необязательного параметра numlines можно ограничить число элементов в списке.

# JLD2.read_array! — Function

read_array!(v::Array, f::JLDFile, rr)

Заполняет массив v содержимым файла JLD f в текущей позиции с использованием ReadRepresentation rr.

# JLD2.read_attr_data — Method

read_attr_data(f::JLDFile, attr::ReadAttribute, expected_datatype::H5Datatype,
               rr::ReadRepresentation)

Считывает данные из атрибута с использованием определенного типа данных HDF5 и ReadRepresentation. При несоответствии типа данных HDF5 вызывает исключение UnsupportedFeatureException. Таким образом, обеспечивается большая стабильность типов с одновременной проверкой данных.

# JLD2.read_attr_data — Method

read_attr_data(f::JLDFile, attr::ReadAttribute)

Считывает данные из атрибута.

# JLD2.read_attribute — Method

read_attribute(io::IO, f::JLDFile)

Считывает сообщение атрибута в текущей позиции объекта io. Поддерживается сообщение атрибута версии 1 или 2.

# JLD2.read_compressed_array! — Function

read_compressed_array!(v::Array, f::JLDFile, rr, data_length::Int, ::Val{filter_id})

Заполняет массив v сжатым содержимым файла JLD f в текущей позиции с использованием ReadRepresentation rr, причем предполагается, что сжатые данные имеют длину data_length.

# JLD2.read_data — Function

read_data(f::JLDFile, dataspace::ReadDataspace, datatype_class::UInt8,
          datatype_offset::Int64, data_offset::Int64[, filters::FilterPipeline,
          header_offset::RelOffset, attributes::Vector{ReadAttribute}])

Считывает данные из файла. Если datatype_class имеет значение typemax(UInt8), тип данных считается сохраненным, а datatype_offset указывает на смещение заголовка сохраненного типа данных. В противном случае datatype_offset указывает на смещение атрибута типа данных.

# JLD2.read_scalar — Function

read_scalar(f::JLDFile, rr, header_offset::RelOffset)

Считывает необработанные данные, представляющие скаляр, с использованием представления чтения rr начиная с текущей позиции в файле JLD f. header_offset — это смещение RelOffset заголовка объекта, используемое для разрешения циклов.

# JLD2.read_size — Method

read_size(io::IO, flags::UInt8)

Загружает размер переменной длины в соответствии с флагами. Предполагается, что первые два бита флага имеют следующе значение: 0 — длина поля имени ссылки имеет размер 1 байт; 1 — длина поля имени ссылки имеет размер 2 байта; 2 — длина поля имени ссылки имеет размер 4 байта; 3 — длина поля имени ссылки имеет размер 8 байтов. Размер возвращается в виде значения типа Int.

# JLD2.readas — Method

readas(::Type)::Type

Экспериментальные функции: JLD2.readas можно перегрузить, чтобы переопределить то, в виде какого типа считывается сохраненный тип; такой вариант применяется для пользовательской сериализации вместе с JLD2.writeas.

Типичный случай — пользовательская сериализация параметрических типов, когда не все параметры типов доступны во время считывания. Рассмотрим следующий пример для анонимной функции fun внутри Foo:

struct Foo{F<:Function}
    fun::F
end
struct FooSerialization
    fun
end
JLD2.writeas(::Type{<:Foo}) = FooSerialization
Base.convert(::Type{<:FooSerialization}, f::Foo) = FooSerialization(f.fun)

JLD2.readas(::Type{<:FooSerialization}) = Foo
struct UndefinedFunction <:Function
    fun
end
(f::UndefinedFunction)(args...; kwargs...) = error("The function $(f.fun) is not defined")
function Base.convert(::Type{<:Foo}, f::FooSerialization)
    isa(f.fun, Function) && return Foo(f.fun)
    return Foo(UndefinedFunction(f.fun))
end

Если мы включим эти определения, вызовем jldsave("foo.jld2"; foo=Foo(x->x^2)), перезапустим Julia, включим определения снова и вызовем foo = jldopen("foo.jld2") do io; io["foo"]; end, то получим foo::Foo{UndefinedFunction} и foo::FooSerialization с приведенным выше определением JLD2.readas и без него, соответственно.

# JLD2.save_group — Method

save_group(g::Group) -> RelOffset

Сохраняет группу в файл, обновляя ее, если она уже была сохранена. Возвращает UNDEFINED_ADDRESS, если группа уже была сохранена, или смещение новой группы в противном случае.

# JLD2.save_object — Method

save_object(filename, x)

Сохраняет объект x в новом JLD2-файле в filename. Если файл существует по этому пути, он будет перезаписан.

Поскольку формат JLD2 требует, чтобы у всех объектов было имя, объект будет сохранен как single_stored_object. Чтобы сохранить несколько объектов, используйте макрос @save, jldopen или API FileIO.

Пример

Сохранение строки hello в JLD2-файле example.jld2:

hello = "world"
save_object("example.jld2", hello)

# JLD2.shorttypestring — Method

shorttypestring(::Type{ <:UnknownType})

Преобразовывает UnknownType в соответствующую строку. Используется только в целях создания имен для воссоздаваемых типов. См. также typestring.

# JLD2.skip_to_aligned! — Function

skip_to_aligned!(io, rel=0)

Выполняет переход к ближайшей позиции, выровненной по кратному 8 байтов относительно rel.

# JLD2.symbol_length — Method

symbol_length(x::Symbol)

Возвращает длину строки, представленной x.

# JLD2.typestring — Method

typestring(::Type{ <:UnknownType})

Преобразовывает UnknownType в соответствующую строку. Используется только для предупреждения при возникновении ошибок воссоздания. См. также shorttypestring.

# JLD2.write_link — Method

write_link(cio, name, offset)

Записывает сообщение ссылки в текущей позиции в cio.

# JLD2.@load — Macro

@load filename var1 [var2 ...]

Загружает одну или несколько переменных var1,... из JLD2-файла filename в текущую область и возвращает вектор имен загруженных переменных.

В интерактивном режиме форма вызова @load "somefile.jld2" загружает все переменные из файла "somefile.jld2" в текущую область. Эта форма поддерживает только литеральные имена файлов, и ее следует избегать в более стабильном коде, чтобы было понятно, откуда взялись переменные.

Пример

Для загрузки переменных hello и foo из файла example.jld2 используйте такой вызов:

@load "example.jld2" hello foo

# JLD2.@save — Macro

@save filename var1 [var2 ...]
@save filename {compress=true} var1 name2=var2

Записывает одну или несколько переменных var1,... из текущей области в файл JLD2 filename.

Для использования в интерактивном режиме можно сохранить все переменные в глобальной области текущего модуля с помощью @save filename. В более стабильном коде предпочтительнее использовать явную форму во избежание сохранения лишних переменных.

Пример

Сохранение строки hello и массива xs в JLD2-файле example.jld2:

hello = "world"
xs = [1,2,3]
@save "example.jld2" hello xs

Для передачи параметров в команду сохранения используйте {}

@save "example.jld2" {compress=true} hello xs

Для сохранения переменных под другим именем используйте стандартный синтаксис присваивания

@save "example.jld2" greeting=hello xarray = xs