Struct JournalFile 

pub struct JournalFile<M>
where
    M: MemoryMap,
{
    pub seal_options: Option<SealOptions>,
    /* private fields */
}

A reader for systemd journal files that efficiently maps small regions of the file into memory.

Memory Management

This implementation uses a window-based memory mapping strategy similar to systemd’s original implementation. Instead of mapping the entire file, it maintains a small set of memory-mapped windows and reuses them as needed.

Concurrency and Safety

JournalFile uses interior mutability to provide a safe API with the following characteristics:

• The window manager is wrapped in a GuardedCell which owns both the WindowManager and its guard flag, providing interior mutability with integrated guard-based exclusion.
• The guard flag ensures only one object can be active at a time.
• Methods like data_object() return a ValueGuard<T> that automatically releases the guard when dropped.

This design ensures that memory safety is maintained even though references to memory-mapped regions could be invalidated when new objects are created.

Fields

seal_options: Option<SealOptions>

Implementations

impl<M> JournalFile<M>

where M: MemoryMap,

pub fn visit_bucket<'a, H, V>( &'a self, hash_table: Option<H>, hash: u64, visitor: V, ) -> Result<Option<<V as BucketVisitor<'a>>::Output>, JournalError>

where H: HashTable<Object = <V as BucketVisitor<'a>>::Object>, V: BucketVisitor<'a>,

pub fn open( file: &File, window_size: u64, ) -> Result<JournalFile<M>, JournalError>

pub fn open_with_strategy( file: &File, window_size: u64, strategy: ExperimentalMmapStrategy, ) -> Result<JournalFile<M>, JournalError>

pub fn open_path( path: impl AsRef<Path>, window_size: u64, ) -> Result<JournalFile<M>, JournalError>

pub fn open_path_with_strategy( path: impl AsRef<Path>, window_size: u64, strategy: ExperimentalMmapStrategy, ) -> Result<JournalFile<M>, JournalError>

pub fn open_snapshot( file: &File, window_size: u64, strategy: ExperimentalMmapStrategy, ) -> Result<JournalFile<M>, JournalError>

pub fn open_path_snapshot( path: impl AsRef<Path>, window_size: u64, strategy: ExperimentalMmapStrategy, ) -> Result<JournalFile<M>, JournalError>

pub fn file(&self) -> &File

pub fn hash(&self, data: &[u8]) -> u64

pub fn hash_parts(&self, payload: PayloadParts<'_>) -> u64

pub fn entry_list(&self) -> Option<List>

pub fn entry_offsets( &self, offsets: &mut Vec<NonZero<u64>>, ) -> Result<(), JournalError>

pub fn entry_data_object_offsets( &self, entry_offset: NonZero<u64>, offsets: &mut Vec<NonZero<u64>>, ) -> Result<(), JournalError>

pub fn journal_header_ref(&self) -> &JournalHeader

pub fn data_hash_table_map(&self) -> Option<&M>

pub fn field_hash_table_map(&self) -> Option<&M>

pub fn data_hash_table_ref(&self) -> Option<DataHashTable<&[u8]>>

pub fn field_hash_table_ref(&self) -> Option<FieldHashTable<&[u8]>>

pub fn object_header_ref( &self, position: NonZero<u64>, ) -> Result<&ObjectHeader, JournalError>

pub fn read_bytes_at( &self, offset: u64, size: u64, ) -> Result<Vec<u8>, JournalError>

Reads raw bytes from the file at the given offset. Returns a copied Vec so no borrow on the window manager is held.

pub fn offset_array_ref( &self, offset: NonZero<u64>, ) -> Result<ValueGuard<'_, OffsetArrayObject<&[u8]>>, JournalError>

pub fn field_ref( &self, offset: NonZero<u64>, ) -> Result<ValueGuard<'_, FieldObject<&[u8]>>, JournalError>

pub fn entry_ref( &self, offset: NonZero<u64>, ) -> Result<ValueGuard<'_, EntryObject<&[u8]>>, JournalError>

pub fn data_ref( &self, offset: NonZero<u64>, ) -> Result<ValueGuard<'_, DataObject<&[u8]>>, JournalError>

pub fn tag_ref( &self, offset: NonZero<u64>, ) -> Result<ValueGuard<'_, TagObject<&[u8]>>, JournalError>

pub fn find_field_offset( &self, hash: u64, payload: &[u8], ) -> Result<Option<NonZero<u64>>, JournalError>

pub fn data_object_directed_partition_point<F>( &self, data_offset: NonZero<u64>, predicate: F, direction: Direction, ) -> Result<Option<NonZero<u64>>, JournalError>

where F: Fn(NonZero<u64>) -> Result<bool, JournalError>,

Run a directed partition point query on a data object’s entry array

This finds the first/last entry (depending on direction) that satisfies the given predicate in the entry array chain of the data object.

pub fn fields(&self) -> FieldIterator<'_, M>

Creates an iterator over all field objects in the field hash table

pub fn field_data_objects<'a>( &'a self, field_name: &'a [u8], ) -> Result<FieldDataIterator<'a, M>, JournalError>

Creates an iterator over all DATA objects for the specified field

pub fn field_data_objects_with_offsets<'a>( &'a self, field_name: &'a [u8], ) -> Result<FieldDataOffsetIterator<'a, M>, JournalError>

Creates an iterator over all DATA objects for the specified field, including the on-disk DATA object offset.

pub fn entry_data_objects( &self, entry_offset: NonZero<u64>, ) -> Result<EntryDataIterator<'_, M>, JournalError>

Creates an iterator over all DATA objects for a specific entry

pub fn bucket_utilization(&self) -> Option<BucketUtilization>

Get hash table bucket utilization statistics

pub fn duration(&self) -> Option<Duration>

Get the duration covered by all entries in the journal Returns None if the journal is empty or contains only one entry

impl JournalFile<MmapMut>

pub fn open_for_append( file: &File, window_size: u64, ) -> Result<JournalFile<MmapMut>, JournalError>

impl<M> JournalFile<M>

where M: MemoryMapMut,

pub fn sync(&mut self) -> Result<(), JournalError>

Syncs all file data to disk, ensuring all changes are persisted

This performs a two-step sync process:

1. Flushes memory-mapped regions to the file page cache (msync)
2. Syncs the file page cache to physical disk (fdatasync)

pub fn post_change(&mut self) -> Result<(), JournalError>

Trigger a stock-reader-visible post-change notification after mmap append.

pub fn create_successor( &self, file: &File, max_file_size: Option<u64>, ) -> Result<JournalFile<M>, JournalError>

Creates a successor journal file with optimized bucket sizes based on this file’s utilization

pub fn create_successor_with_file_mode( &self, file: &File, max_file_size: Option<u64>, file_mode: u32, ) -> Result<JournalFile<M>, JournalError>

pub fn create( file: &File, options: JournalFileOptions, ) -> Result<JournalFile<M>, JournalError>

pub fn journal_header_mut(&mut self) -> &mut JournalHeader

pub fn data_hash_table_mut(&mut self) -> Option<DataHashTable<&mut [u8]>>

pub fn field_hash_table_mut(&mut self) -> Option<FieldHashTable<&mut [u8]>>

pub fn offset_array_mut( &self, offset: NonZero<u64>, capacity: Option<NonZero<u64>>, ) -> Result<ValueGuard<'_, OffsetArrayObject<&mut [u8]>>, JournalError>

pub fn field_mut( &self, offset: NonZero<u64>, size: Option<u64>, ) -> Result<ValueGuard<'_, FieldObject<&mut [u8]>>, JournalError>

pub fn entry_mut( &self, offset: NonZero<u64>, size: Option<u64>, ) -> Result<ValueGuard<'_, EntryObject<&mut [u8]>>, JournalError>

pub fn data_mut( &self, offset: NonZero<u64>, size: Option<u64>, ) -> Result<ValueGuard<'_, DataObject<&mut [u8]>>, JournalError>

pub fn tag_mut( &self, offset: NonZero<u64>, new: bool, ) -> Result<ValueGuard<'_, TagObject<&mut [u8]>>, JournalError>

impl<M> JournalFile<M>

where M: MemoryMapMut,

pub fn data_hash_table_set_tail_offset( &mut self, hash: u64, object_offset: NonZero<u64>, ) -> Result<(), JournalError>

pub fn field_hash_table_set_tail_offset( &mut self, hash: u64, object_offset: NonZero<u64>, ) -> Result<(), JournalError>

impl<M> JournalFile<M>

where M: MemoryMap,

pub fn find_data_offset( &self, hash: u64, payload: &[u8], ) -> Result<Option<NonZero<u64>>, JournalError>

pub fn find_data_offset_parts( &self, hash: u64, payload: PayloadParts<'_>, ) -> Result<Option<NonZero<u64>>, JournalError>