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
74
75
//! 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 shared through `Arc`, while each potentially
//! blocking `pwrite`/`seek_write` call runs on the shared bounded disk I/O
//! worker pool. This is
//! fundamentally different from the legacy `Arc<tokio::sync::Mutex<...>>`
//! design which held the lock across async await points and serialized writes.
//!
//! Here the lock is held only for the synchronous syscall, never across
//! `.await` points. When multiple [`PositionedDiskWriter`] instances
//! reference the same file path (each opening its own file descriptor), writes
//! to non-overlapping ranges can execute concurrently at the OS level. The
//! positioned-write APIs use an explicit offset and do not mutate a shared file
//! cursor. They do not make an arbitrary multi-byte write transactional or
//! guarantee atomic visibility to concurrent readers; callers must coordinate
//! overlapping ranges themselves.
pub
// 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`.