std: Add IntoRaw{Fd,Handle,Socket} traits

This commit is an implementation of [RFC 1174][rfc] which adds three new traits
to the standard library:

* `IntoRawFd` - implemented on Unix for all I/O types (files, sockets, etc)
* `IntoRawHandle` - implemented on Windows for files, processes, etc
* `IntoRawSocket` - implemented on Windows for networking types

[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1174-into-raw-fd-socket-handle-traits.md

Closes #27062

6 files changed, 89 insertions, 6 deletions

diff --git a/src/libstd/sys/windows/ext/io.rs b/src/libstd/sys/windows/ext/io.rs
index f4717eb2425..185f1abe64b 100644
--- a/src/libstd/sys/windows/ext/io.rs
+++ b/src/libstd/sys/windows/ext/io.rs
@@ -13,7 +13,7 @@
 use fs;
 use os::windows::raw;
 use net;
-use sys_common::{self, AsInner, FromInner};
+use sys_common::{self, AsInner, FromInner, IntoInner};
 use sys;
 
 /// Raw HANDLEs.
@@ -50,6 +50,18 @@ pub trait FromRawHandle {
     unsafe fn from_raw_handle(handle: RawHandle) -> Self;
 }
 
+/// A trait to express the ability to consume an object and acquire ownership of
+/// its raw `HANDLE`.
+#[unstable(feature = "into_raw_os", reason = "recently added API")]
+pub trait IntoRawHandle {
+    /// Consumes this object, returning the raw underlying handle.
+    ///
+    /// This function **transfers ownership** of the underlying handle to the
+    /// caller. Callers are then the unique owners of the handle and must close
+    /// it once it's no longer needed.
+    fn into_raw_handle(self) -> RawHandle;
+}
+
 #[stable(feature = "rust1", since = "1.0.0")]
 impl AsRawHandle for fs::File {
     fn as_raw_handle(&self) -> RawHandle {
@@ -65,6 +77,12 @@ impl FromRawHandle for fs::File {
     }
 }
 
+impl IntoRawHandle for fs::File {
+    fn into_raw_handle(self) -> RawHandle {
+        self.into_inner().into_handle().into_raw() as *mut _
+    }
+}
+
 /// Extract raw sockets.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait AsRawSocket {
@@ -90,6 +108,18 @@ pub trait FromRawSocket {
     unsafe fn from_raw_socket(sock: RawSocket) -> Self;
 }
 
+/// A trait to express the ability to consume an object and acquire ownership of
+/// its raw `SOCKET`.
+#[unstable(feature = "into_raw_os", reason = "recently added API")]
+pub trait IntoRawSocket {
+    /// Consumes this object, returning the raw underlying socket.
+    ///
+    /// This function **transfers ownership** of the underlying socket to the
+    /// caller. Callers are then the unique owners of the socket and must close
+    /// it once it's no longer needed.
+    fn into_raw_socket(self) -> RawSocket;
+}
+
 #[stable(feature = "rust1", since = "1.0.0")]
 impl AsRawSocket for net::TcpStream {
     fn as_raw_socket(&self) -> RawSocket {
@@ -130,3 +160,21 @@ impl FromRawSocket for net::UdpSocket {
         net::UdpSocket::from_inner(sys_common::net::UdpSocket::from_inner(sock))
     }
 }
+
+impl IntoRawSocket for net::TcpStream {
+    fn into_raw_socket(self) -> RawSocket {
+        self.into_inner().into_socket().into_inner()
+    }
+}
+
+impl IntoRawSocket for net::TcpListener {
+    fn into_raw_socket(self) -> RawSocket {
+        self.into_inner().into_socket().into_inner()
+    }
+}
+
+impl IntoRawSocket for net::UdpSocket {
+    fn into_raw_socket(self) -> RawSocket {
+        self.into_inner().into_socket().into_inner()
+    }
+}
diff --git a/src/libstd/sys/windows/ext/process.rs b/src/libstd/sys/windows/ext/process.rs
index 6f59be2687a..fde21e9a798 100644
--- a/src/libstd/sys/windows/ext/process.rs
+++ b/src/libstd/sys/windows/ext/process.rs
@@ -12,10 +12,10 @@
 
 #![stable(feature = "process_extensions", since = "1.2.0")]
 
-use os::windows::io::{FromRawHandle, RawHandle, AsRawHandle};
+use os::windows::io::{FromRawHandle, RawHandle, AsRawHandle, IntoRawHandle};
 use process;
 use sys;
-use sys_common::{AsInner, FromInner};
+use sys_common::{AsInner, FromInner, IntoInner};
 
 #[stable(feature = "process_extensions", since = "1.2.0")]
 impl FromRawHandle for process::Stdio {
@@ -32,6 +32,12 @@ impl AsRawHandle for process::Child {
     }
 }
 
+impl IntoRawHandle for process::Child {
+    fn into_raw_handle(self) -> RawHandle {
+        self.into_inner().into_handle().into_raw() as *mut _
+    }
+}
+
 #[stable(feature = "process_extensions", since = "1.2.0")]
 impl AsRawHandle for process::ChildStdin {
     fn as_raw_handle(&self) -> RawHandle {
@@ -52,3 +58,21 @@ impl AsRawHandle for process::ChildStderr {
         self.as_inner().handle().raw() as *mut _
     }
 }
+
+impl IntoRawHandle for process::ChildStdin {
+    fn into_raw_handle(self) -> RawHandle {
+        self.into_inner().into_handle().into_raw() as *mut _
+    }
+}
+
+impl IntoRawHandle for process::ChildStdout {
+    fn into_raw_handle(self) -> RawHandle {
+        self.into_inner().into_handle().into_raw() as *mut _
+    }
+}
+
+impl IntoRawHandle for process::ChildStderr {
+    fn into_raw_handle(self) -> RawHandle {
+        self.into_inner().into_handle().into_raw() as *mut _
+    }
+}
diff --git a/src/libstd/sys/windows/fs.rs b/src/libstd/sys/windows/fs.rs
index 890cc455d5d..5dd84e9f71e 100644
--- a/src/libstd/sys/windows/fs.rs
+++ b/src/libstd/sys/windows/fs.rs
@@ -319,6 +319,8 @@ impl File {
 
     pub fn handle(&self) -> &Handle { &self.handle }
 
+    pub fn into_handle(self) -> Handle { self.handle }
+
     fn reparse_point<'a>(&self,
                          space: &'a mut [u8; c::MAXIMUM_REPARSE_DATA_BUFFER_SIZE])
                          -> io::Result<(libc::DWORD, &'a c::REPARSE_DATA_BUFFER)> {
@@ -357,8 +359,6 @@ impl File {
             Ok(PathBuf::from(OsString::from_wide(subst)))
         }
     }
-
-    pub fn into_handle(self) -> Handle { self.handle }
 }
 
 impl FromInner<libc::HANDLE> for File {
diff --git a/src/libstd/sys/windows/net.rs b/src/libstd/sys/windows/net.rs
index b765bc6e500..d58355ed1fe 100644
--- a/src/libstd/sys/windows/net.rs
+++ b/src/libstd/sys/windows/net.rs
@@ -21,7 +21,7 @@ use rt;
 use sync::Once;
 use sys;
 use sys::c;
-use sys_common::{AsInner, FromInner};
+use sys_common::{AsInner, FromInner, IntoInner};
 use sys_common::net::{setsockopt, getsockopt};
 use time::Duration;
 
@@ -184,3 +184,11 @@ impl AsInner<libc::SOCKET> for Socket {
 impl FromInner<libc::SOCKET> for Socket {
     fn from_inner(sock: libc::SOCKET) -> Socket { Socket(sock) }
 }
+
+impl IntoInner<libc::SOCKET> for Socket {
+    fn into_inner(self) -> libc::SOCKET {
+        let ret = self.0;
+        mem::forget(self);
+        ret
+    }
+}
diff --git a/src/libstd/sys/windows/pipe.rs b/src/libstd/sys/windows/pipe.rs
index b2a6607314a..a7ece66e0f1 100644
--- a/src/libstd/sys/windows/pipe.rs
+++ b/src/libstd/sys/windows/pipe.rs
@@ -37,6 +37,7 @@ pub fn anon_pipe() -> io::Result<(AnonPipe, AnonPipe)> {
 
 impl AnonPipe {
     pub fn handle(&self) -> &Handle { &self.inner }
+    pub fn into_handle(self) -> Handle { self.inner }
 
     pub fn raw(&self) -> libc::HANDLE { self.inner.raw() }
 
diff --git a/src/libstd/sys/windows/process.rs b/src/libstd/sys/windows/process.rs
index 0b0268d4746..ca33e11eea0 100644
--- a/src/libstd/sys/windows/process.rs
+++ b/src/libstd/sys/windows/process.rs
@@ -220,6 +220,8 @@ impl Process {
     }
 
     pub fn handle(&self) -> &Handle { &self.handle }
+
+    pub fn into_handle(self) -> Handle { self.handle }
 }
 
 #[derive(PartialEq, Eq, Clone, Copy, Debug)]