1#[cfg(not(io_safety_is_in_std))]
2#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
3use crate::BorrowedFd;
4#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
5use crate::OwnedFd;
6#[cfg(not(io_safety_is_in_std))]
7#[cfg(windows)]
8use crate::{BorrowedHandle, BorrowedSocket};
9#[cfg(windows)]
10use crate::{OwnedHandle, OwnedSocket};
11
12/// A trait to borrow the file descriptor from an underlying object.
13///
14/// This is only available on unix platforms and must be imported in order to
15/// call the method. Windows platforms have a corresponding `AsHandle` and
16/// `AsSocket` set of traits.
17#[cfg(not(io_safety_is_in_std))]
18#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
19pub trait AsFd {
20 /// Borrows the file descriptor.
21 ///
22 /// # Example
23 ///
24 /// ```rust,no_run
25 /// use std::fs::File;
26 /// # use std::io;
27 /// use io_lifetimes::{AsFd, BorrowedFd};
28 ///
29 /// let mut f = File::open("foo.txt")?;
30 /// let borrowed_fd: BorrowedFd<'_> = f.as_fd();
31 /// # Ok::<(), io::Error>(())
32 /// ```
33 fn as_fd(&self) -> BorrowedFd<'_>;
34}
35
36/// A trait to borrow the handle from an underlying object.
37#[cfg(not(io_safety_is_in_std))]
38#[cfg(windows)]
39pub trait AsHandle {
40 /// Borrows the handle.
41 ///
42 /// # Example
43 ///
44 /// ```rust,no_run
45 /// use std::fs::File;
46 /// # use std::io;
47 /// use io_lifetimes::{AsHandle, BorrowedHandle};
48 ///
49 /// let mut f = File::open("foo.txt")?;
50 /// let borrowed_handle: BorrowedHandle<'_> = f.as_handle();
51 /// # Ok::<(), io::Error>(())
52 /// ```
53 fn as_handle(&self) -> BorrowedHandle<'_>;
54}
55
56/// A trait to borrow the socket from an underlying object.
57#[cfg(not(io_safety_is_in_std))]
58#[cfg(windows)]
59pub trait AsSocket {
60 /// Borrows the socket.
61 fn as_socket(&self) -> BorrowedSocket<'_>;
62}
63
64/// A trait to express the ability to consume an object and acquire ownership
65/// of its file descriptor.
66#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
67#[deprecated(
68 since = "1.0.0",
69 note = "`IntoFd` is replaced by `From<...> for OwnedFd` or `Into<OwnedFd>`"
70)]
71pub trait IntoFd {
72 /// Consumes this object, returning the underlying file descriptor.
73 ///
74 /// # Example
75 ///
76 /// ```rust,no_run
77 /// use std::fs::File;
78 /// # use std::io;
79 /// use io_lifetimes::{IntoFd, OwnedFd};
80 ///
81 /// let f = File::open("foo.txt")?;
82 /// let owned_fd: OwnedFd = f.into_fd();
83 /// # Ok::<(), io::Error>(())
84 /// ```
85 fn into_fd(self) -> OwnedFd;
86}
87
88/// A trait to express the ability to consume an object and acquire ownership
89/// of its handle.
90#[cfg(windows)]
91#[deprecated(
92 since = "1.0.0",
93 note = "`IntoHandle` is replaced by `From<...> for OwnedHandle` or `Into<OwnedHandle>`"
94)]
95pub trait IntoHandle {
96 /// Consumes this object, returning the underlying handle.
97 ///
98 /// # Example
99 ///
100 /// ```rust,no_run
101 /// use std::fs::File;
102 /// # use std::io;
103 /// use io_lifetimes::{IntoHandle, OwnedHandle};
104 ///
105 /// let f = File::open("foo.txt")?;
106 /// let owned_handle: OwnedHandle = f.into_handle();
107 /// # Ok::<(), io::Error>(())
108 /// ```
109 fn into_handle(self) -> OwnedHandle;
110}
111
112/// A trait to express the ability to consume an object and acquire ownership
113/// of its socket.
114#[cfg(windows)]
115#[deprecated(
116 since = "1.0.0",
117 note = "`IntoSocket` is replaced by `From<...> for OwnedSocket` or `Into<OwnedSocket>`"
118)]
119pub trait IntoSocket {
120 /// Consumes this object, returning the underlying socket.
121 fn into_socket(self) -> OwnedSocket;
122}
123
124/// A trait to express the ability to construct an object from a file
125/// descriptor.
126#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
127pub trait FromFd {
128 /// Constructs a new instance of `Self` from the given file descriptor.
129 ///
130 /// # Example
131 ///
132 /// ```rust,no_run
133 /// use std::fs::File;
134 /// # use std::io;
135 /// use io_lifetimes::{FromFd, IntoFd, OwnedFd};
136 ///
137 /// let f = File::open("foo.txt")?;
138 /// let owned_fd: OwnedFd = f.into_fd();
139 /// let f = File::from_fd(owned_fd);
140 /// # Ok::<(), io::Error>(())
141 /// ```
142 #[deprecated(
143 since = "1.0.0",
144 note = "`FromFd::from_fd` is replaced by `From<OwnedFd>::from`"
145 )]
146 fn from_fd(owned: OwnedFd) -> Self;
147
148 /// Constructs a new instance of `Self` from the given file descriptor
149 /// converted from `into_owned`.
150 ///
151 /// # Example
152 ///
153 /// ```rust,no_run
154 /// use std::fs::File;
155 /// # use std::io;
156 /// use io_lifetimes::{FromFd, IntoFd};
157 ///
158 /// let f = File::open("foo.txt")?;
159 /// let f = File::from_into_fd(f);
160 /// # Ok::<(), io::Error>(())
161 /// ```
162 #[inline]
163 fn from_into_fd<Owned: Into<OwnedFd>>(into_owned: Owned) -> Self
164 where
165 Self: Sized + From<OwnedFd>,
166 {
167 Self::from(into_owned.into())
168 }
169}
170
171/// A trait to express the ability to construct an object from a handle.
172#[cfg(windows)]
173pub trait FromHandle {
174 /// Constructs a new instance of `Self` from the given handle.
175 ///
176 /// # Example
177 ///
178 /// ```rust,no_run
179 /// use std::fs::File;
180 /// # use std::io;
181 /// use io_lifetimes::{FromHandle, IntoHandle, OwnedHandle};
182 ///
183 /// let f = File::open("foo.txt")?;
184 /// let owned_handle: OwnedHandle = f.into_handle();
185 /// let f = File::from_handle(owned_handle);
186 /// # Ok::<(), io::Error>(())
187 /// ```
188 #[deprecated(
189 since = "1.0.0",
190 note = "`FromHandle::from_handle` is replaced by `From<OwnedHandle>::from`"
191 )]
192 fn from_handle(owned: OwnedHandle) -> Self;
193
194 /// Constructs a new instance of `Self` from the given handle converted
195 /// from `into_owned`.
196 ///
197 /// # Example
198 ///
199 /// ```rust,no_run
200 /// use std::fs::File;
201 /// # use std::io;
202 /// use io_lifetimes::{FromHandle, IntoHandle};
203 ///
204 /// let f = File::open("foo.txt")?;
205 /// let f = File::from_into_handle(f);
206 /// # Ok::<(), io::Error>(())
207 /// ```
208 #[inline]
209 fn from_into_handle<Owned: Into<OwnedHandle>>(into_owned: Owned) -> Self
210 where
211 Self: Sized + From<OwnedHandle>,
212 {
213 Self::from(into_owned.into())
214 }
215}
216
217/// A trait to express the ability to construct an object from a socket.
218#[cfg(windows)]
219pub trait FromSocket {
220 /// Constructs a new instance of `Self` from the given socket.
221 #[deprecated(
222 since = "1.0.0",
223 note = "`FromSocket::from_socket` is replaced by `From<OwnedSocket>::from`"
224 )]
225 fn from_socket(owned: OwnedSocket) -> Self;
226
227 /// Constructs a new instance of `Self` from the given socket converted
228 /// from `into_owned`.
229 #[inline]
230 fn from_into_socket<Owned: Into<OwnedSocket>>(into_owned: Owned) -> Self
231 where
232 Self: Sized + From<OwnedSocket>,
233 {
234 Self::from(into_owned.into())
235 }
236}
237
238#[cfg(not(io_safety_is_in_std))]
239#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
240impl<T: AsFd> AsFd for &T {
241 #[inline]
242 fn as_fd(&self) -> BorrowedFd<'_> {
243 T::as_fd(self)
244 }
245}
246
247#[cfg(not(io_safety_is_in_std))]
248#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
249impl<T: AsFd> AsFd for &mut T {
250 #[inline]
251 fn as_fd(&self) -> BorrowedFd<'_> {
252 T::as_fd(self)
253 }
254}
255
256#[cfg(not(io_safety_is_in_std))]
257#[cfg(windows)]
258impl<T: AsHandle> AsHandle for &T {
259 #[inline]
260 fn as_handle(&self) -> BorrowedHandle<'_> {
261 T::as_handle(self)
262 }
263}
264
265#[cfg(not(io_safety_is_in_std))]
266#[cfg(windows)]
267impl<T: AsHandle> AsHandle for &mut T {
268 #[inline]
269 fn as_handle(&self) -> BorrowedHandle<'_> {
270 T::as_handle(self)
271 }
272}
273
274#[cfg(not(io_safety_is_in_std))]
275#[cfg(windows)]
276impl<T: AsSocket> AsSocket for &T {
277 #[inline]
278 fn as_socket(&self) -> BorrowedSocket<'_> {
279 T::as_socket(self)
280 }
281}
282
283#[cfg(not(io_safety_is_in_std))]
284#[cfg(windows)]
285impl<T: AsSocket> AsSocket for &mut T {
286 #[inline]
287 fn as_socket(&self) -> BorrowedSocket<'_> {
288 T::as_socket(self)
289 }
290}
291