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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
// =============================================================================
// Copyright (c) 2026 Haixing Hu.
//
// SPDX-License-Identifier: Apache-2.0
//
// Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Concrete asynchronous file reader handle.
use Debug;
use Formatter;
use Result as FmtResult;
use Result as IoResult;
use Pin;
use Context;
use Poll;
use AsyncByteInput;
use AsyncInput;
use BoxAsyncInput;
use crateOpenedFileInfo;
/// Type-erased asynchronous byte input associated with an opened file.
///
/// Asynchronous providers must report temporary unavailability as
/// `Poll::Pending` and arrange to wake the registered task. Returning
/// `WouldBlock` or `Interrupted` violates the async I/O contract. The safe
/// `qubit-io` read methods expose these errors as `InvalidData` while retaining
/// the original cause chain. Consequently, `read_all` and `read_prefix`
/// classify them as `FsErrorKind::Io`; they do not promote a nested `FsError`
/// to the outer error or promise that a nested error's type/effect is
/// recoverable through `Error::source`. A directly transported typed business
/// error keeps its type, kind, provider, and effect state, but a failed read
/// may already have changed the caller's buffer, so its kind does not prove
/// that the buffer is unchanged. Synchronous interruption retry rules do not
/// apply to asynchronous inputs.
///
/// # Examples
///
/// The application supplies a configured filesystem and a validated path.
///
/// ```rust
/// use qubit_fs::AsyncFileSystem;
/// use qubit_fs::Path;
/// use qubit_fs::read::ReadOptions;
/// use qubit_io::AsyncInput;
///
/// async fn read_prefix(
/// filesystem: &AsyncFileSystem,
/// path: &Path,
/// ) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
/// let mut reader = filesystem.open_reader(path, ReadOptions::default()).await?;
/// let mut prefix = vec![0; 16];
/// let count = reader.read_fully_async(&mut prefix).await?;
/// prefix.truncate(count);
/// Ok(prefix)
/// }
/// ```