asupersync 0.3.0

Spec-first, cancel-correct, capability-secure async runtime for Rust.
Documentation 
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
76
77
78
79
80
81
82
83
84
85
86
87
88
89

//! Async filesystem operations.
//!
//! This module provides async file I/O operations that mirror the `std::fs` API
//! but with async/await support. In Phase 0 (single-threaded runtime), operations
//! are synchronous internally but exposed through async interfaces.
//!
//! # Cancel Safety
//!
//! - `File::open`, `File::create`: Cancel-safe (no partial state)
//! - Read operations: Cancel-safe (partial data discarded by caller)
//! - Write operations: Use `WritePermit` for cancel-safe writes, or accept
//!   potential partial writes on cancellation
//! - `sync_all`, `sync_data`: Cancel-safe (atomic completion)
//! - Seek: Cancel-safe (atomic completion)
//!
//! # Example
//!
//! ```ignore
//! use asupersync::fs::File;
//!
//! async fn example() -> std::io::Result<()> {
//!     // Create and write
//!     let mut file = File::create("test.txt").await?;
//!     file.write_all(b"hello").await?;
//!     file.sync_all().await?;
//!     drop(file);
//!
//!     // Read back
//!     let mut file = File::open("test.txt").await?;
//!     let mut contents = String::new();
//!     file.read_to_string(&mut contents).await?;
//!     Ok(())
//! }
//! ```
//!
//! # Platform Strategy
//!
//! - **Phase 0**: Synchronous I/O wrapped in async interface
//! - **Phase 1+**: Use `spawn_blocking` for thread pool offload
//! - **Future**: io_uring on Linux for true async I/O

mod buf_reader;
mod buf_writer;
mod dir;
mod file;
mod lines;
mod metadata;
mod open_options;
mod path_ops;
mod read_dir;
pub mod vfs;

#[cfg(all(target_os = "linux", feature = "io-uring"))]
pub mod uring;

pub use buf_reader::BufReader;
pub use buf_writer::BufWriter;
pub use dir::{create_dir, create_dir_all, remove_dir, remove_dir_all};
pub use file::File;
pub use lines::Lines;
pub use metadata::{FileType, Metadata, Permissions};
pub use open_options::OpenOptions;
pub use path_ops::{
    canonicalize, copy, hard_link, metadata, read, read_link, read_to_string, remove_file, rename,
    set_permissions, symlink_metadata, write, write_atomic,
};
pub use read_dir::{DirEntry, ReadDir, read_dir};

#[cfg(all(target_os = "linux", feature = "io-uring"))]
pub use uring::IoUringFile;

#[cfg(unix)]
pub use path_ops::symlink;

#[cfg(windows)]
pub use path_ops::{symlink_dir, symlink_file};

pub use std::io::SeekFrom;

pub use vfs::{UnixVfs, UnixVfsFile, Vfs, VfsFile};

/// Checks whether a path exists with explicit error reporting.
///
/// Unlike `Path::exists`, this preserves I/O errors instead of collapsing them
/// to `false`. Behavior mirrors Tokio's `fs::try_exists`.
pub async fn try_exists(path: impl AsRef<std::path::Path>) -> std::io::Result<bool> {
    let path = path.as_ref().to_owned();
    crate::runtime::spawn_blocking_io(move || path.try_exists()).await
}