Документация Engee

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

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

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

CommittedDatatype

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

CustomSerialization{T,S}

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

GlobalHeap

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

Group(file)

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

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

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

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

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

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

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

H5Datatype

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

IndirectPointer

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

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

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

JLDFile{T<:IO}

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

JLDWriteSession{T}

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

ReadRepresentation{T,ODR}

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

RelOffset

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

SharedDatatype

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

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

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

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

Upgrade(T)

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

behead(T)

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

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

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

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

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

group_payload_size(g)

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

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

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

jld_finalizer(f::JLDFile)

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

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

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...).

link_size(name::String)

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

links_size(pairs)

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

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

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

load_datatypes(f::JLDFile)

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

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")
lookup_offset(g::Group, name::AbstractString) -> RelOffset

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

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

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

prewrite(f::JLDFile)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 указывает на смещение атрибута типа данных.

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

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

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

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

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 и без него, соответственно.

save_group(g::Group) -> RelOffset

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

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)
shorttypestring(::Type{ <:UnknownType})

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

skip_to_aligned!(io, rel=0)

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

symbol_length(x::Symbol)

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

typestring(::Type{ <:UnknownType})

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

write_link(cio, name, offset)

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

@load filename var1 [var2 ...]

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

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

Пример

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

@load "example.jld2" hello foo
@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