Struct JournalFile 

pub struct JournalFile<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: MemoryMap> JournalFile<M>

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

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

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

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

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

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

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

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

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<NonZeroU64>) -> Result<()>

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

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: NonZeroU64) -> Result<&ObjectHeader>

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

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: NonZeroU64, ) -> Result<ValueGuard<'_, OffsetArrayObject<&[u8]>>>

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

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

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

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

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

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

where F: Fn(NonZeroU64) -> Result<bool>,

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

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

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: NonZeroU64, ) -> Result<EntryDataIterator<'_, M>>

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<Self>

impl<M: MemoryMapMut> JournalFile<M>

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

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

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

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

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<Self>

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

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: NonZeroU64, capacity: Option<NonZeroU64>, ) -> Result<ValueGuard<'_, OffsetArrayObject<&mut [u8]>>>

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

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

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

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

impl<M: MemoryMapMut> JournalFile<M>

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

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

impl<M: MemoryMap> JournalFile<M>

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

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