[rustc.git] / vendor / io-lifetimes / src / traits.rs

#[cfg(not(io_safety_is_in_std))]
#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
use crate::BorrowedFd;
#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
use crate::OwnedFd;
#[cfg(not(io_safety_is_in_std))]
#[cfg(windows)]
use crate::{BorrowedHandle, BorrowedSocket};
#[cfg(windows)]
use crate::{OwnedHandle, OwnedSocket};

/// A trait to borrow the file descriptor from an underlying object.
///
/// This is only available on unix platforms and must be imported in order to
/// call the method. Windows platforms have a corresponding `AsHandle` and
/// `AsSocket` set of traits.
#[cfg(not(io_safety_is_in_std))]
#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
pub trait AsFd {
    /// Borrows the file descriptor.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use std::fs::File;
    /// # use std::io;
    /// use io_lifetimes::{AsFd, BorrowedFd};
    ///
    /// let mut f = File::open("foo.txt")?;
    /// let borrowed_fd: BorrowedFd<'_> = f.as_fd();
    /// # Ok::<(), io::Error>(())
    /// ```
    fn as_fd(&self) -> BorrowedFd<'_>;
}

/// A trait to borrow the handle from an underlying object.
#[cfg(not(io_safety_is_in_std))]
#[cfg(windows)]
pub trait AsHandle {
    /// Borrows the handle.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use std::fs::File;
    /// # use std::io;
    /// use io_lifetimes::{AsHandle, BorrowedHandle};
    ///
    /// let mut f = File::open("foo.txt")?;
    /// let borrowed_handle: BorrowedHandle<'_> = f.as_handle();
    /// # Ok::<(), io::Error>(())
    /// ```
    fn as_handle(&self) -> BorrowedHandle<'_>;
}

/// A trait to borrow the socket from an underlying object.
#[cfg(not(io_safety_is_in_std))]
#[cfg(windows)]
pub trait AsSocket {
    /// Borrows the socket.
    fn as_socket(&self) -> BorrowedSocket<'_>;
}

/// A trait to express the ability to consume an object and acquire ownership
/// of its file descriptor.
#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
#[deprecated(
    since = "1.0.0",
    note = "`IntoFd` is replaced by `From<...> for OwnedFd` or `Into<OwnedFd>`"
)]
pub trait IntoFd {
    /// Consumes this object, returning the underlying file descriptor.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use std::fs::File;
    /// # use std::io;
    /// use io_lifetimes::{IntoFd, OwnedFd};
    ///
    /// let f = File::open("foo.txt")?;
    /// let owned_fd: OwnedFd = f.into_fd();
    /// # Ok::<(), io::Error>(())
    /// ```
    fn into_fd(self) -> OwnedFd;
}

/// A trait to express the ability to consume an object and acquire ownership
/// of its handle.
#[cfg(windows)]
#[deprecated(
    since = "1.0.0",
    note = "`IntoHandle` is replaced by `From<...> for OwnedHandle` or `Into<OwnedHandle>`"
)]
pub trait IntoHandle {
    /// Consumes this object, returning the underlying handle.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use std::fs::File;
    /// # use std::io;
    /// use io_lifetimes::{IntoHandle, OwnedHandle};
    ///
    /// let f = File::open("foo.txt")?;
    /// let owned_handle: OwnedHandle = f.into_handle();
    /// # Ok::<(), io::Error>(())
    /// ```
    fn into_handle(self) -> OwnedHandle;
}

/// A trait to express the ability to consume an object and acquire ownership
/// of its socket.
#[cfg(windows)]
#[deprecated(
    since = "1.0.0",
    note = "`IntoSocket` is replaced by `From<...> for OwnedSocket` or `Into<OwnedSocket>`"
)]
pub trait IntoSocket {
    /// Consumes this object, returning the underlying socket.
    fn into_socket(self) -> OwnedSocket;
}

/// A trait to express the ability to construct an object from a file
/// descriptor.
#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
pub trait FromFd {
    /// Constructs a new instance of `Self` from the given file descriptor.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use std::fs::File;
    /// # use std::io;
    /// use io_lifetimes::{FromFd, IntoFd, OwnedFd};
    ///
    /// let f = File::open("foo.txt")?;
    /// let owned_fd: OwnedFd = f.into_fd();
    /// let f = File::from_fd(owned_fd);
    /// # Ok::<(), io::Error>(())
    /// ```
    #[deprecated(
        since = "1.0.0",
        note = "`FromFd::from_fd` is replaced by `From<OwnedFd>::from`"
    )]
    fn from_fd(owned: OwnedFd) -> Self;

    /// Constructs a new instance of `Self` from the given file descriptor
    /// converted from `into_owned`.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use std::fs::File;
    /// # use std::io;
    /// use io_lifetimes::{FromFd, IntoFd};
    ///
    /// let f = File::open("foo.txt")?;
    /// let f = File::from_into_fd(f);
    /// # Ok::<(), io::Error>(())
    /// ```
    #[inline]
    fn from_into_fd<Owned: Into<OwnedFd>>(into_owned: Owned) -> Self
    where
        Self: Sized + From<OwnedFd>,
    {
        Self::from(into_owned.into())
    }
}

/// A trait to express the ability to construct an object from a handle.
#[cfg(windows)]
pub trait FromHandle {
    /// Constructs a new instance of `Self` from the given handle.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use std::fs::File;
    /// # use std::io;
    /// use io_lifetimes::{FromHandle, IntoHandle, OwnedHandle};
    ///
    /// let f = File::open("foo.txt")?;
    /// let owned_handle: OwnedHandle = f.into_handle();
    /// let f = File::from_handle(owned_handle);
    /// # Ok::<(), io::Error>(())
    /// ```
    #[deprecated(
        since = "1.0.0",
        note = "`FromHandle::from_handle` is replaced by `From<OwnedHandle>::from`"
    )]
    fn from_handle(owned: OwnedHandle) -> Self;

    /// Constructs a new instance of `Self` from the given handle converted
    /// from `into_owned`.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use std::fs::File;
    /// # use std::io;
    /// use io_lifetimes::{FromHandle, IntoHandle};
    ///
    /// let f = File::open("foo.txt")?;
    /// let f = File::from_into_handle(f);
    /// # Ok::<(), io::Error>(())
    /// ```
    #[inline]
    fn from_into_handle<Owned: Into<OwnedHandle>>(into_owned: Owned) -> Self
    where
        Self: Sized + From<OwnedHandle>,
    {
        Self::from(into_owned.into())
    }
}

/// A trait to express the ability to construct an object from a socket.
#[cfg(windows)]
pub trait FromSocket {
    /// Constructs a new instance of `Self` from the given socket.
    #[deprecated(
        since = "1.0.0",
        note = "`FromSocket::from_socket` is replaced by `From<OwnedSocket>::from`"
    )]
    fn from_socket(owned: OwnedSocket) -> Self;

    /// Constructs a new instance of `Self` from the given socket converted
    /// from `into_owned`.
    #[inline]
    fn from_into_socket<Owned: Into<OwnedSocket>>(into_owned: Owned) -> Self
    where
        Self: Sized + From<OwnedSocket>,
    {
        Self::from(into_owned.into())
    }
}

#[cfg(not(io_safety_is_in_std))]
#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
impl<T: AsFd> AsFd for &T {
    #[inline]
    fn as_fd(&self) -> BorrowedFd<'_> {
        T::as_fd(self)
    }
}

#[cfg(not(io_safety_is_in_std))]
#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
impl<T: AsFd> AsFd for &mut T {
    #[inline]
    fn as_fd(&self) -> BorrowedFd<'_> {
        T::as_fd(self)
    }
}

#[cfg(not(io_safety_is_in_std))]
#[cfg(windows)]
impl<T: AsHandle> AsHandle for &T {
    #[inline]
    fn as_handle(&self) -> BorrowedHandle<'_> {
        T::as_handle(self)
    }
}

#[cfg(not(io_safety_is_in_std))]
#[cfg(windows)]
impl<T: AsHandle> AsHandle for &mut T {
    #[inline]
    fn as_handle(&self) -> BorrowedHandle<'_> {
        T::as_handle(self)
    }
}

#[cfg(not(io_safety_is_in_std))]
#[cfg(windows)]
impl<T: AsSocket> AsSocket for &T {
    #[inline]
    fn as_socket(&self) -> BorrowedSocket<'_> {
        T::as_socket(self)
    }
}

#[cfg(not(io_safety_is_in_std))]
#[cfg(windows)]
impl<T: AsSocket> AsSocket for &mut T {
    #[inline]
    fn as_socket(&self) -> BorrowedSocket<'_> {
        T::as_socket(self)
    }
}
Commit	Line	Data
487cf647	1	#[cfg(not(io_safety_is_in_std))]
353b0b11	2	#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
064997fb	3	use crate::BorrowedFd;
353b0b11	4	#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
064997fb	5	use crate::OwnedFd;
487cf647	6	#[cfg(not(io_safety_is_in_std))]
064997fb FG	7	#[cfg(windows)]
	8	use crate::{BorrowedHandle, BorrowedSocket};
	9	#[cfg(windows)]
	10	use 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.
487cf647	17	#[cfg(not(io_safety_is_in_std))]
353b0b11	18	#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
064997fb FG	19	pub trait AsFd {
	20	/// Borrows the file descriptor.
	21	///
	22	/// # Example
	23	///
	24	/// ```rust,no_run
064997fb FG	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.
487cf647	37	#[cfg(not(io_safety_is_in_std))]
064997fb FG	38	#[cfg(windows)]
	39	pub trait AsHandle {
	40	/// Borrows the handle.
	41	///
	42	/// # Example
	43	///
	44	/// ```rust,no_run
064997fb FG	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.
487cf647	57	#[cfg(not(io_safety_is_in_std))]
064997fb FG	58	#[cfg(windows)]
	59	pub 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.
353b0b11	66	#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
487cf647 FG	67	#[deprecated(
	68	since = "1.0.0",
	69	note = "`IntoFd` is replaced by `From<...> for OwnedFd` or `Into<OwnedFd>`"
	70	)]
064997fb FG	71	pub trait IntoFd {
	72	/// Consumes this object, returning the underlying file descriptor.
	73	///
	74	/// # Example
	75	///
	76	/// ```rust,no_run
064997fb FG	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)]
487cf647 FG	91	#[deprecated(
	92	since = "1.0.0",
	93	note = "`IntoHandle` is replaced by `From<...> for OwnedHandle` or `Into<OwnedHandle>`"
	94	)]
064997fb FG	95	pub trait IntoHandle {
	96	/// Consumes this object, returning the underlying handle.
	97	///
	98	/// # Example
	99	///
	100	/// ```rust,no_run
064997fb FG	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)]
487cf647 FG	115	#[deprecated(
	116	since = "1.0.0",
	117	note = "`IntoSocket` is replaced by `From<...> for OwnedSocket` or `Into<OwnedSocket>`"
	118	)]
064997fb FG	119	pub 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.
353b0b11	126	#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
064997fb FG	127	pub trait FromFd {
	128	/// Constructs a new instance of `Self` from the given file descriptor.
	129	///
	130	/// # Example
	131	///
	132	/// ```rust,no_run
064997fb FG	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	/// ```
487cf647 FG	142	#[deprecated(
	143	since = "1.0.0",
	144	note = "`FromFd::from_fd` is replaced by `From<OwnedFd>::from`"
	145	)]
064997fb FG	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
064997fb FG	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]
487cf647	163	fn from_into_fd<Owned: Into<OwnedFd>>(into_owned: Owned) -> Self
064997fb	164	where
487cf647	165	Self: Sized + From<OwnedFd>,
064997fb	166	{
487cf647	167	Self::from(into_owned.into())
064997fb FG	168	}
	169	}
	170
	171	/// A trait to express the ability to construct an object from a handle.
	172	#[cfg(windows)]
	173	pub trait FromHandle {
	174	/// Constructs a new instance of `Self` from the given handle.
	175	///
	176	/// # Example
	177	///
	178	/// ```rust,no_run
064997fb FG	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	/// ```
487cf647 FG	188	#[deprecated(
	189	since = "1.0.0",
	190	note = "`FromHandle::from_handle` is replaced by `From<OwnedHandle>::from`"
	191	)]
064997fb FG	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
064997fb FG	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]
487cf647	209	fn from_into_handle<Owned: Into<OwnedHandle>>(into_owned: Owned) -> Self
064997fb	210	where
487cf647	211	Self: Sized + From<OwnedHandle>,
064997fb	212	{
487cf647	213	Self::from(into_owned.into())
064997fb FG	214	}
	215	}
	216
	217	/// A trait to express the ability to construct an object from a socket.
	218	#[cfg(windows)]
	219	pub trait FromSocket {
	220	/// Constructs a new instance of `Self` from the given socket.
487cf647 FG	221	#[deprecated(
	222	since = "1.0.0",
	223	note = "`FromSocket::from_socket` is replaced by `From<OwnedSocket>::from`"
	224	)]
064997fb FG	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]
487cf647	230	fn from_into_socket<Owned: Into<OwnedSocket>>(into_owned: Owned) -> Self
064997fb	231	where
487cf647	232	Self: Sized + From<OwnedSocket>,
064997fb	233	{
487cf647	234	Self::from(into_owned.into())
064997fb FG	235	}
	236	}
	237
487cf647	238	#[cfg(not(io_safety_is_in_std))]
353b0b11	239	#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
064997fb FG	240	impl<T: AsFd> AsFd for &T {
	241	#[inline]
	242	fn as_fd(&self) -> BorrowedFd<'_> {
	243	T::as_fd(self)
	244	}
	245	}
	246
487cf647	247	#[cfg(not(io_safety_is_in_std))]
353b0b11	248	#[cfg(any(unix, target_os = "wasi", target_os = "hermit"))]
064997fb FG	249	impl<T: AsFd> AsFd for &mut T {
	250	#[inline]
	251	fn as_fd(&self) -> BorrowedFd<'_> {
	252	T::as_fd(self)
	253	}
	254	}
	255
487cf647	256	#[cfg(not(io_safety_is_in_std))]
064997fb FG	257	#[cfg(windows)]
	258	impl<T: AsHandle> AsHandle for &T {
	259	#[inline]
	260	fn as_handle(&self) -> BorrowedHandle<'_> {
	261	T::as_handle(self)
	262	}
	263	}
	264
487cf647	265	#[cfg(not(io_safety_is_in_std))]
064997fb FG	266	#[cfg(windows)]
	267	impl<T: AsHandle> AsHandle for &mut T {
	268	#[inline]
	269	fn as_handle(&self) -> BorrowedHandle<'_> {
	270	T::as_handle(self)
	271	}
	272	}
	273
487cf647	274	#[cfg(not(io_safety_is_in_std))]
064997fb FG	275	#[cfg(windows)]
	276	impl<T: AsSocket> AsSocket for &T {
	277	#[inline]
	278	fn as_socket(&self) -> BorrowedSocket<'_> {
	279	T::as_socket(self)
	280	}
	281	}
	282
487cf647	283	#[cfg(not(io_safety_is_in_std))]
064997fb FG	284	#[cfg(windows)]
	285	impl<T: AsSocket> AsSocket for &mut T {
	286	#[inline]
	287	fn as_socket(&self) -> BorrowedSocket<'_> {
	288	T::as_socket(self)
	289	}
	290	}