1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
//! Positioned disk writer using OS-native `pwrite`/`seek_write` for concurrent
//! writes to non-overlapping offsets without a global async mutex.
//!
//! Platform support:
//! - Unix: [`std::os::unix::fs::FileExt::write_at`] (wraps `pwrite(2)`)
//! - Windows: [`std::os::windows::fs::FileExt::seek_write`]
//!
//! # Concurrency model
//!
//! The underlying file handle is wrapped in a [`std::sync::Mutex`] held ONLY
//! for the brief duration of each synchronous `pwrite`/`seek_write` syscall.
//! This is fundamentally different from the legacy
//! `Arc<tokio::sync::Mutex<DirectDiskAdaptor>>` design which held the lock
//! across async await points and serialized all writes.
//!
//! Here the lock is held only for the synchronous syscall (microseconds),
//! never across `.await` points. When multiple [`PositionedDiskWriter`]
//! instances reference the same file path (each opening its own file
//! descriptor), non-overlapping writes execute concurrently at the OS level
//! because `pwrite` is atomic and offset-based — it does not mutate the
//! shared file cursor.
// Re-export the primary public types and factory function.
pub use PositionedDiskWriter;
pub use IoUringDiskWriter;
use Path;
use crateSeekableDiskWriter;
/// Create the best available positioned writer for the current platform.
///
/// On Linux with the `io_uring` feature enabled, returns an [`IoUringDiskWriter`]
/// that uses the io_uring syscall interface for async positioned I/O. On all
/// other platforms (or without the feature), returns a [`PositionedDiskWriter`]
/// that uses synchronous `pwrite`/`seek_write`.
///
/// # Runtime requirement (io_uring)
///
/// When the `io_uring` feature is enabled on Linux, the returned writer MUST be
/// driven from within a `tokio_uring` runtime context (e.g. inside
/// `tokio_uring::start`). Using it inside a regular `tokio` runtime will panic
/// because `tokio_uring::fs` operations require the io_uring reactor.
///
/// This factory is intentionally NOT wired into the default download pipeline.
/// The main pipeline uses [`PositionedDiskWriter`] directly via `CachedDiskWriter`.