Struct PositionedDiskWriter 

pub struct PositionedDiskWriter { /* private fields */ }

A disk writer that performs positioned (offset-based) I/O via OS-native pwrite/seek_write syscalls.

The file descriptor is protected by a std::sync::Mutex held only for the duration of each synchronous syscall — never across .await points. This enables true concurrency for non-overlapping writes when multiple writers reference the same file.

Uses std::fs::File (not tokio::fs::File) because FileExt::write_at is a synchronous method available only on std::fs::File. Since pwrite is a fast non-blocking syscall (it never waits on async I/O completion), running it synchronously inside a tokio task is acceptable — it does not stall the runtime for meaningful durations.

Implementations

impl PositionedDiskWriter

pub fn new(path: &Path, total_size: Option<u64>) -> Self

Create a new PositionedDiskWriter for the given path.

If total_size is provided and the file is newly created (size 0), the file is pre-allocated to total_size bytes on first open. This avoids fragmentation and enables concurrent writes to arbitrary offsets without per-write file extension.

pub fn total_size(&self) -> Option<u64>

Returns the configured total size, if any.

pub fn raw_fd(&self) -> Option<RawFd>

Returns the raw file descriptor of the underlying file, if open.

This is used by the Linux splice download path to obtain the file fd for splice(2) zero-copy transfer. Returns None if the file has not been opened yet (caller should call open() first).

The caller must ensure the writer is not dropped or closed while the returned fd is in use. The fd is valid only while the writer holds the file open.

Trait Implementations

impl SeekableDiskWriter for PositionedDiskWriter

fn write_bytes_at<'life0, 'async_trait>( &'life0 mut self, offset: u64, data: Bytes, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Zero-copy write: accepts Bytes directly. Since pwrite takes &[u8], we simply dereference the Bytes (no copy — Bytes derefs to [u8]).

fn open<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn write_at<'life0, 'life1, 'async_trait>( &'life0 mut self, offset: u64, data: &'life1 [u8], ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn read_at<'life0, 'life1, 'async_trait>( &'life0 mut self, offset: u64, buf: &'life1 mut [u8], ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn truncate<'life0, 'async_trait>( &'life0 mut self, length: u64, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn flush<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn len<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<u64>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn path(&self) -> &Path

fn close<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Close the writer and release underlying file resources.