Struct TensogramFile 

pub struct TensogramFile { /* private fields */ }

A handle for reading/writing Tensogram message files.

Supports local files, memory-mapped files (mmap feature), and remote object stores (remote feature) via a unified API.

Implementations

impl TensogramFile

pub fn open(path: impl AsRef<Path>) -> Result<Self>

pub fn open_source( source: impl AsRef<str>, scan_opts: Option<RemoteScanOptions>, ) -> Result<Self>

Open a local file or remote URL.

Auto-detects remote URLs (s3://, s3a://, gs://, az://, azure://, http://, https://) when the remote feature is enabled; otherwise treats source as a local path.

scan_opts configures the remote scan walker. None (or Some(RemoteScanOptions::default())) runs the pipelined bidirectional walker, which is the default. Pass Some(RemoteScanOptions { bidirectional: false }) to force a forward-only walk. For local paths the value is silently ignored — local scanning runs through framing::scan_file with the in-memory ScanOptions, which is unrelated to this remote-backend flag.

pub fn open_remote( source: &str, storage_options: &BTreeMap<String, String>, scan_opts: Option<RemoteScanOptions>, ) -> Result<Self>

Open a remote file with explicit storage options (credentials, region, etc.) and scan-walker configuration.

scan_opts = None (or Some(RemoteScanOptions::default())) runs the pipelined bidirectional walker (the default). Pass Some(RemoteScanOptions { bidirectional: false }) to force a forward-only walk. See crate::RemoteScanOptions for the per-flag rationale.

pub fn create(path: impl AsRef<Path>) -> Result<Self>

Create a new local file for writing (truncates if exists).

pub fn open_mmap(path: impl AsRef<Path>) -> Result<Self>

Open a file with memory-mapped I/O for zero-copy reads.

The file is mapped into memory and scan() runs directly on the mapped buffer. read_message() returns a copy from the mapped region.

pub fn message_count(&self) -> Result<usize>

pub fn message_layouts(&self) -> Result<Vec<MessageLayout>>

Per-message (byte_offset, byte_length) layout, in scan order.

Triggers a full scan if the file has not yet been scanned. For remote files opened with crate::RemoteScanOptions::bidirectional enabled, the returned layouts are identical to the forward-only walk — only the discovery path differs.

pub fn append( &mut self, global_metadata: &GlobalMetadata, descriptors: &[(&DataObjectDescriptor, &[u8])], options: &EncodeOptions, ) -> Result<()>

pub fn read_message(&self, index: usize) -> Result<Vec<u8>>

pub fn messages(&self) -> Result<Vec<Vec<u8>>>

👎Deprecated:

Use message_count() + read_message(index) for lazy access

pub fn decode_message( &self, index: usize, options: &DecodeOptions, ) -> Result<(GlobalMetadata, Vec<DecodedObject>)>

pub fn iter(&self) -> Result<FileMessageIter>

pub fn path(&self) -> Option<&Path>

pub fn source(&self) -> String

pub fn invalidate_offsets(&mut self)

pub fn decode_metadata(&self, msg_idx: usize) -> Result<GlobalMetadata>

pub fn decode_descriptors( &self, msg_idx: usize, ) -> Result<(GlobalMetadata, Vec<DataObjectDescriptor>)>

pub fn decode_object( &self, msg_idx: usize, obj_idx: usize, options: &DecodeOptions, ) -> Result<(GlobalMetadata, DataObjectDescriptor, Vec<u8>)>

pub fn decode_range_batch( &self, msg_indices: &[usize], obj_idx: usize, ranges: &[(u64, u64)], options: &DecodeOptions, ) -> Result<Vec<(DataObjectDescriptor, Vec<Vec<u8>>)>>

pub fn decode_object_batch( &self, msg_indices: &[usize], obj_idx: usize, options: &DecodeOptions, ) -> Result<Vec<(GlobalMetadata, DataObjectDescriptor, Vec<u8>)>>

pub fn decode_range( &self, msg_idx: usize, obj_idx: usize, ranges: &[(u64, u64)], options: &DecodeOptions, ) -> Result<(DataObjectDescriptor, Vec<Vec<u8>>)>

pub fn is_remote(&self) -> bool

pub async fn open_async(path: impl AsRef<Path>) -> Result<Self>

pub async fn message_count_async(&self) -> Result<usize>

pub async fn message_layouts_async(&self) -> Result<Vec<MessageLayout>>

Async sibling of Self::message_layouts.

pub async fn read_message_async(&self, index: usize) -> Result<Vec<u8>>

pub async fn decode_message_async( &self, index: usize, options: &DecodeOptions, ) -> Result<(GlobalMetadata, Vec<DecodedObject>)>

pub async fn open_source_async( source: impl AsRef<str>, scan_opts: Option<RemoteScanOptions>, ) -> Result<Self>

Async sibling of Self::open_source. See that method for the scan_opts contract.

pub async fn open_remote_async( source: &str, storage_options: &BTreeMap<String, String>, scan_opts: Option<RemoteScanOptions>, ) -> Result<Self>

Async sibling of Self::open_remote. See that method for the scan_opts contract.

pub async fn decode_metadata_async( &self, msg_idx: usize, ) -> Result<GlobalMetadata>

pub async fn decode_descriptors_async( &self, msg_idx: usize, ) -> Result<(GlobalMetadata, Vec<DataObjectDescriptor>)>

pub async fn decode_object_async( &self, msg_idx: usize, obj_idx: usize, options: &DecodeOptions, ) -> Result<(GlobalMetadata, DataObjectDescriptor, Vec<u8>)>

pub async fn decode_range_async( &self, msg_idx: usize, obj_idx: usize, ranges: &[(u64, u64)], options: &DecodeOptions, ) -> Result<(DataObjectDescriptor, Vec<Vec<u8>>)>

pub async fn prefetch_layouts_async(&self, msg_indices: &[usize]) -> Result<()>

pub async fn decode_object_batch_async( &self, msg_indices: &[usize], obj_idx: usize, options: &DecodeOptions, ) -> Result<Vec<(GlobalMetadata, DataObjectDescriptor, Vec<u8>)>>

pub async fn decode_range_batch_async( &self, msg_indices: &[usize], obj_idx: usize, ranges: &[(u64, u64)], options: &DecodeOptions, ) -> Result<Vec<(DataObjectDescriptor, Vec<Vec<u8>>)>>