Module reference 

Reference elements and the dataspace selections region references carry.

Two element layouts exist for the pre-1.12 reference kinds, both written by h5py 3.x today (H5Tref.c):

H5R_OBJECT1          sizeof_addr bytes   the target's object header address
H5R_DATASET_REGION1  sizeof_addr + 4     a global-heap id: collection
                                         address then a u32 object index

The heap object a region reference points at is the target’s object header address followed by the serialized selection (H5R__encode_token_region_compat), whose wire format lives in the H5S serializers (H5S__hyper_serialize, H5S__point_serialize, H5S__all_serialize, H5S__none_serialize).

The 1.12 kinds — H5R_OBJECT2, H5R_DATASET_REGION2 and H5R_ATTR, all written as H5T_STD_REF — share one element layout instead (H5T__ref_disk_getsize):

type (1) | flags (1) | encoded reference           an H5R_OBJECT2 with no
                                                   external file, stored
                                                   inline
type (1) | flags (1) | size (4) | heap id          everything else, whose
                                                   encoded reference is a
                                                   global-heap blob

and the encoded reference itself is H5R__encode: a token (its length, then the target’s object header address), then — when the flags carry H5R_IS_EXTERNAL — the name of the file the target lives in, then the serialized selection for a region and the attribute name for an attribute reference.

Structs

DecodedReference

Everything H5R__decode recovers from an encoded reference: where the target is, and what is named there.

Enums

Reference

One reference element, decoded and resolved against the file it came from.

ReferenceElementImage

What one reference element holds — the encode-side mirror of RevisedElement, which is what a reader splits an element back into.

ReferenceTarget

What a reference names beyond the object its token points at.

RevisedElement

Where a 1.12 element keeps its encoded reference.

Constants

REVISED_BLOB_TOKEN_OFFSET

Where the object token sits inside a blob encode_revised_blob built: behind the one byte that gives its length.

Functions

decode_object_element

The address a H5R_OBJECT1 element names, or None for a null reference.

decode_region_element

The (collection address, object index) a H5R_DATASET_REGION1 element names, or None when the element is a null reference.

decode_region_heap_object

Split a region reference’s heap object into the target’s object header address and the selection over it.

decode_revised_body

Decode an encoded 1.12 reference — H5R__decode from the token onwards — into where its target is and what it names there, or None when the token names no object.

decode_revised_element

Split a 1.12 reference element into its kind and the encoded reference.

encode_reference_element

The image one reference element has, at the size its datatype declares.

encode_revised_blob

The encoded reference a 1.12 blob holds, less the two-byte header the element keeps — H5R__encode from the token onwards, which is exactly what decode_revised_body reads back.