1#[cfg(not(io_safety_is_in_std))]
2#[cfg(any(unix, target_os = "wasi"))]
3use crate::BorrowedFd;
4#[cfg(any(unix, target_os = "wasi"))]
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"))]
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"))]
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"))]
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"))]
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"))]
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