io_lifetimes/
traits.rs

1#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
2use crate::OwnedFd;
3#[cfg(windows)]
4use crate::{OwnedHandle, OwnedSocket};
5
6/// A trait to express the ability to consume an object and acquire ownership
7/// of its file descriptor.
8#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
9#[deprecated(
10    since = "1.0.0",
11    note = "`IntoFd` is replaced by `From<...> for OwnedFd` or `Into<OwnedFd>`"
12)]
13pub trait IntoFd {
14    /// Consumes this object, returning the underlying file descriptor.
15    ///
16    /// # Example
17    ///
18    /// ```rust,no_run
19    /// use std::fs::File;
20    /// # use std::io;
21    /// use io_lifetimes::{IntoFd, OwnedFd};
22    ///
23    /// let f = File::open("foo.txt")?;
24    /// let owned_fd: OwnedFd = f.into_fd();
25    /// # Ok::<(), io::Error>(())
26    /// ```
27    fn into_fd(self) -> OwnedFd;
28}
29
30/// A trait to express the ability to consume an object and acquire ownership
31/// of its handle.
32#[cfg(windows)]
33#[deprecated(
34    since = "1.0.0",
35    note = "`IntoHandle` is replaced by `From<...> for OwnedHandle` or `Into<OwnedHandle>`"
36)]
37pub trait IntoHandle {
38    /// Consumes this object, returning the underlying handle.
39    ///
40    /// # Example
41    ///
42    /// ```rust,no_run
43    /// use std::fs::File;
44    /// # use std::io;
45    /// use io_lifetimes::{IntoHandle, OwnedHandle};
46    ///
47    /// let f = File::open("foo.txt")?;
48    /// let owned_handle: OwnedHandle = f.into_handle();
49    /// # Ok::<(), io::Error>(())
50    /// ```
51    fn into_handle(self) -> OwnedHandle;
52}
53
54/// A trait to express the ability to consume an object and acquire ownership
55/// of its socket.
56#[cfg(windows)]
57#[deprecated(
58    since = "1.0.0",
59    note = "`IntoSocket` is replaced by `From<...> for OwnedSocket` or `Into<OwnedSocket>`"
60)]
61pub trait IntoSocket {
62    /// Consumes this object, returning the underlying socket.
63    fn into_socket(self) -> OwnedSocket;
64}
65
66/// A trait to express the ability to construct an object from a file
67/// descriptor.
68#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
69pub trait FromFd {
70    /// Constructs a new instance of `Self` from the given file descriptor.
71    ///
72    /// # Example
73    ///
74    /// ```rust,no_run
75    /// use std::fs::File;
76    /// # use std::io;
77    /// use io_lifetimes::{FromFd, IntoFd, OwnedFd};
78    ///
79    /// let f = File::open("foo.txt")?;
80    /// let owned_fd: OwnedFd = f.into_fd();
81    /// let f = File::from_fd(owned_fd);
82    /// # Ok::<(), io::Error>(())
83    /// ```
84    #[deprecated(
85        since = "1.0.0",
86        note = "`FromFd::from_fd` is replaced by `From<OwnedFd>::from`"
87    )]
88    fn from_fd(owned: OwnedFd) -> Self;
89
90    /// Constructs a new instance of `Self` from the given file descriptor
91    /// converted from `into_owned`.
92    ///
93    /// # Example
94    ///
95    /// ```rust,no_run
96    /// use std::fs::File;
97    /// # use std::io;
98    /// use io_lifetimes::{FromFd, IntoFd};
99    ///
100    /// let f = File::open("foo.txt")?;
101    /// let f = File::from_into_fd(f);
102    /// # Ok::<(), io::Error>(())
103    /// ```
104    #[inline]
105    fn from_into_fd<Owned: Into<OwnedFd>>(into_owned: Owned) -> Self
106    where
107        Self: Sized + From<OwnedFd>,
108    {
109        Self::from(into_owned.into())
110    }
111}
112
113/// A trait to express the ability to construct an object from a handle.
114#[cfg(windows)]
115pub trait FromHandle {
116    /// Constructs a new instance of `Self` from the given handle.
117    ///
118    /// # Example
119    ///
120    /// ```rust,no_run
121    /// use std::fs::File;
122    /// # use std::io;
123    /// use io_lifetimes::{FromHandle, IntoHandle, OwnedHandle};
124    ///
125    /// let f = File::open("foo.txt")?;
126    /// let owned_handle: OwnedHandle = f.into_handle();
127    /// let f = File::from_handle(owned_handle);
128    /// # Ok::<(), io::Error>(())
129    /// ```
130    #[deprecated(
131        since = "1.0.0",
132        note = "`FromHandle::from_handle` is replaced by `From<OwnedHandle>::from`"
133    )]
134    fn from_handle(owned: OwnedHandle) -> Self;
135
136    /// Constructs a new instance of `Self` from the given handle converted
137    /// from `into_owned`.
138    ///
139    /// # Example
140    ///
141    /// ```rust,no_run
142    /// use std::fs::File;
143    /// # use std::io;
144    /// use io_lifetimes::{FromHandle, IntoHandle};
145    ///
146    /// let f = File::open("foo.txt")?;
147    /// let f = File::from_into_handle(f);
148    /// # Ok::<(), io::Error>(())
149    /// ```
150    #[inline]
151    fn from_into_handle<Owned: Into<OwnedHandle>>(into_owned: Owned) -> Self
152    where
153        Self: Sized + From<OwnedHandle>,
154    {
155        Self::from(into_owned.into())
156    }
157}
158
159/// A trait to express the ability to construct an object from a socket.
160#[cfg(windows)]
161pub trait FromSocket {
162    /// Constructs a new instance of `Self` from the given socket.
163    #[deprecated(
164        since = "1.0.0",
165        note = "`FromSocket::from_socket` is replaced by `From<OwnedSocket>::from`"
166    )]
167    fn from_socket(owned: OwnedSocket) -> Self;
168
169    /// Constructs a new instance of `Self` from the given socket converted
170    /// from `into_owned`.
171    #[inline]
172    fn from_into_socket<Owned: Into<OwnedSocket>>(into_owned: Owned) -> Self
173    where
174        Self: Sized + From<OwnedSocket>,
175    {
176        Self::from(into_owned.into())
177    }
178}
io_lifetimes/traits.rs

io_lifetimes/
traits.rs
