pub struct ObjectHeader {
pub flags: u8,
pub times: Option<ObjectTimes>,
pub messages: Vec<ObjectHeaderMessage>,
}Expand description
Object Header v2.
Fields§
§flags: u8Header flags byte: the optional prefix fields (attribute thresholds) and the attribute creation-order policy.
Two groups of bits are not held here, because each describes the
image rather than the header. Bit 5 (H5O_HDR_STORE_TIMES) is derived
from times at encode and stripped at decode, so the
flag and the four values it announces cannot disagree. Bits 0-1, the
chunk-0 size field width, are chosen at encode for the size chunk 0
turns out to have — the narrowest field that expresses it, as
H5O_apply_ohdr picks it (H5Oint.c:459-464) — and stripped at decode
for the same reason. Setting either by hand here does nothing.
times: Option<ObjectTimes>The stored times, when this object tracks them.
messages: Vec<ObjectHeaderMessage>The ordered list of header messages.
Implementations§
Source§impl ObjectHeader
impl ObjectHeader
Sourcepub fn new() -> Self
pub fn new() -> Self
Create a new, empty object header with default flags: no timestamps, no attribute creation order, no non-default thresholds.
Sourcepub fn recorded_times(&self) -> Option<ObjectTimes>
pub fn recorded_times(&self) -> Option<ObjectTimes>
The times this header records, wherever its version keeps them.
One answer for both versions, which store a different number of times
in different places: version 2 keeps all four in the prefix under
H5O_HDR_STORE_TIMES, and version 1 keeps at most one, in an
H5O_MTIME_NEW message. None means the object was created with
H5Pset_obj_track_times(false) — or is a version-1 group or committed
datatype, whose header has nowhere to record a time even while the
property is on, since only H5D__update_oh_info calls H5O_touch_oh
with the force that creates the message (H5Dint.c:1022-1026).
The one time a version-1 header stores fills all four fields. Only
ObjectTimes::change is written back for that version — it is the
field H5O_touch_oh moves to now on both versions (H5Oint.c:1290-1345)
— so the other three are there to keep one struct across both versions
rather than to claim the file said anything about them.
Sourcepub fn add_message(&mut self, msg_type: u8, flags: u8, data: Vec<u8>)
pub fn add_message(&mut self, msg_type: u8, flags: u8, data: Vec<u8>)
Append a message to the object header.
Sourcepub fn add_message_indexed(
&mut self,
msg_type: u8,
flags: u8,
data: Vec<u8>,
creation_index: u16,
)
pub fn add_message_indexed( &mut self, msg_type: u8, flags: u8, data: Vec<u8>, creation_index: u16, )
Append a message carrying a creation index.
The index reaches the file only when the header’s flags bit 2 says the
creation order is tracked; libhdf5 does not encode the field otherwise
(H5O_SIZEOF_MSGHDR_OH).
Sourcepub fn set_attribute_creation_order(&mut self, order: CreationOrder)
pub fn set_attribute_creation_order(&mut self, order: CreationOrder)
Declare order as this object’s attribute creation-order policy.
H5Pget_attr_creation_order reads these two bits back out of the
header, not out of the Attribute Info message (H5Pocpl.c), so they
are what makes an object report its attributes as creation-ordered.
Setting TRACKED also widens every message envelope by the two-byte
creation index.
Sourcepub fn attribute_creation_order(&self) -> CreationOrder
pub fn attribute_creation_order(&self) -> CreationOrder
This object’s attribute creation-order policy, as its flag bits
declare it — the reverse of
set_attribute_creation_order,
and what a reopen must consult so a rewrite re-declares what the file
already says.
Sourcepub fn has_creation_order(&self) -> bool
pub fn has_creation_order(&self) -> bool
Whether attribute creation order tracking is enabled (flags bit 2).
Sourcepub fn message_envelope_size(&self) -> usize
pub fn message_envelope_size(&self) -> usize
Bytes a message envelope takes: type, size and flags, plus the creation
index when this header tracks one (H5O_SIZEOF_MSGHDR_OH).
Sourcepub fn encode(&self) -> FormatResult<Vec<u8>>
pub fn encode(&self) -> FormatResult<Vec<u8>>
Encode the object header to a byte vector, including “OHDR” signature and trailing checksum, with every message in chunk 0.
Fails when any message payload exceeds MAX_MESSAGE_SIZE — see
check_message_sizes.
Sourcepub fn plan_chunks(
&self,
format: ObjectFormat,
capacity: usize,
ctx: &FormatContext,
) -> FormatResult<ChunkPlan>
pub fn plan_chunks( &self, format: ObjectFormat, capacity: usize, ctx: &FormatContext, ) -> FormatResult<ChunkPlan>
How this header divides between chunk 0 and its continuation chunk
when chunk 0’s message area holds at most capacity bytes.
The whole point of a plan is that both sizes are known before either
chunk has an address: the caller allocates the continuation from
continuation_size and hands the
address back to encode_chunked, which is the
only way chunk 0 can name a block that does not exist yet.
Messages fill chunk 0 in order and the rest go to the continuation, so a message never moves ahead of one that was written before it.
Sourcepub fn plan_chunks_in(
&self,
format: ObjectFormat,
block: usize,
ctx: &FormatContext,
) -> FormatResult<ChunkPlan>
pub fn plan_chunks_in( &self, format: ObjectFormat, block: usize, ctx: &FormatContext, ) -> FormatResult<ChunkPlan>
How this header divides when chunk 0 is written over a block-byte
block — the one an existing header occupies, which a rewrite keeps so
that every reference naming the header stays good.
Messages that fit leave the rest of the block padded, as
H5O__chunk_serialize leaves a chunk whose messages shrank; past it,
the plan is plan_chunks’s over the block’s
message area. A version-2 chunk 0 is sized under the narrowest chunk-0
size field that can express its area, the one that leaves the most of
the block to messages, so a header libhdf5 sized exactly for its
messages takes them back without spilling. Refused for a block the
chunk cannot describe: one too short
for the prefix, or, in version 1, one whose message area is not a
multiple of eight — version 1 has no gap, so every byte of the area
has to belong to a message.
Sourcepub fn encode_chunked(
&self,
plan: &ChunkPlan,
format: ObjectFormat,
ctx: &FormatContext,
continuation_addr: u64,
nlink: u32,
) -> FormatResult<(Vec<u8>, Option<Vec<u8>>)>
pub fn encode_chunked( &self, plan: &ChunkPlan, format: ObjectFormat, ctx: &FormatContext, continuation_addr: u64, nlink: u32, ) -> FormatResult<(Vec<u8>, Option<Vec<u8>>)>
Encode this header as plan divides it, in version format, with the
continuation chunk at continuation_addr.
Returns chunk 0 and, when the plan spills, the continuation chunk’s
image. continuation_addr is ignored for a plan that does not spill,
and nlink reaches the file only in the version-1 prefix (see
encode_for).
Sourcepub fn decode(buf: &[u8]) -> FormatResult<(Self, usize)>
pub fn decode(buf: &[u8]) -> FormatResult<(Self, usize)>
Decode an object header from a byte buffer. Returns the parsed header and the number of bytes consumed from the buffer.
Source§impl ObjectHeader
impl ObjectHeader
Sourcepub fn encode_v1(&self, nlink: u32) -> FormatResult<Vec<u8>>
pub fn encode_v1(&self, nlink: u32) -> FormatResult<Vec<u8>>
Encode this header in the version-1 format, with nlink as the object
reference count and every message in chunk 0.
The differences from encode are all
H5O_ALIGN_OLD’s doing: no signature and no checksum, a two-byte
message type, three reserved bytes where version 2 puts the optional
creation index, and every message body padded out to eight bytes with
the padded length in the size field. Refuses the two version-2
prefix fields — see check_v1_encodable.
Sourcepub fn encode_for(
&self,
format: ObjectFormat,
nlink: u32,
) -> FormatResult<Vec<u8>>
pub fn encode_for( &self, format: ObjectFormat, nlink: u32, ) -> FormatResult<Vec<u8>>
Encode this header in the version format calls for.
nlink reaches the file only in the version-1 layout; the version-2
header has no reference-count field (an object with more than one hard
link carries an Object Reference Count message instead).
Source§impl ObjectHeader
impl ObjectHeader
Sourcepub fn decode_v1(buf: &[u8]) -> FormatResult<(Self, usize)>
pub fn decode_v1(buf: &[u8]) -> FormatResult<(Self, usize)>
Decode a v1 object header from a byte buffer.
v1 headers do NOT have the “OHDR” signature or a checksum. The layout is:
Byte 0: version = 1
Byte 1: reserved
Bytes 2-3: num_messages (u16 LE)
Bytes 4-7: obj_ref_count (u32 LE)
Bytes 8-11: header_data_size (u32 LE) — size of message data in first chunk
Messages follow, each:
type: u16 LE
data_size: u16 LE
flags: u8
reserved: 3 bytes
data: data_size bytes (padded to 8-byte alignment)Sourcepub fn decode_any(buf: &[u8]) -> FormatResult<(Self, usize)>
pub fn decode_any(buf: &[u8]) -> FormatResult<(Self, usize)>
Auto-detect and decode either v1 or v2 object header.
Checks for the “OHDR” signature to decide v2; otherwise tries v1.