auto merge of #19169 : aturon/rust/fds, r=alexcrichton

This PR adds some internal infrastructure to allow the private `std::sys` module to access internal representation details of `std::io`.

It then exposes those details in two new, platform-specific API surfaces: `std::os::unix` and `std::os::windows`.

To start with, these will provide the ability to extract file descriptors, HANDLEs, SOCKETs, and so on from `std::io` types.

More functionality, and more specific platforms (e.g. `std::os::linux`) will be added over time.

Closes #18897

9 files changed, 231 insertions, 15 deletions

diff --git a/src/libstd/sys/common/mod.rs b/src/libstd/sys/common/mod.rs
index 77edd7c5c4e..e382ec261a0 100644
--- a/src/libstd/sys/common/mod.rs
+++ b/src/libstd/sys/common/mod.rs
@@ -13,7 +13,7 @@
 
 use io::{mod, IoError, IoResult};
 use prelude::*;
-use sys::{last_error, retry, fs};
+use sys::{last_error, retry};
 use c_str::CString;
 use num::Int;
 use path::BytesContainer;
@@ -84,10 +84,9 @@ pub fn keep_going(data: &[u8], f: |*const u8, uint| -> i64) -> i64 {
     return (origamt - amt) as i64;
 }
 
-// traits for extracting representations from
-
-pub trait AsFileDesc {
-    fn as_fd(&self) -> &fs::FileDesc;
+// A trait for extracting representations from std::io types
+pub trait AsInner<Inner> {
+    fn as_inner(&self) -> &Inner;
 }
 
 pub trait ProcessConfig<K: BytesContainer, V: BytesContainer> {
diff --git a/src/libstd/sys/unix/ext.rs b/src/libstd/sys/unix/ext.rs
new file mode 100644
index 00000000000..ae3c939bf78
--- /dev/null
+++ b/src/libstd/sys/unix/ext.rs
@@ -0,0 +1,107 @@
+// Copyright 2014 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! Experimental extensions to `std` for Unix platforms.
+//!
+//! For now, this module is limited to extracting file descriptors,
+//! but its functionality will grow over time.
+//!
+//! # Example
+//!
+//! ```rust,ignore
+//! #![feature(globs)]
+//!
+//! use std::io::fs::File;
+//! use std::os::unix::prelude::*;
+//!
+//! fn main() {
+//!     let f = File::create(&Path::new("foo.txt")).unwrap();
+//!     let fd = f.as_raw_fd();
+//!
+//!     // use fd with native unix bindings
+//! }
+//! ```
+
+#![experimental]
+
+use sys_common::AsInner;
+use libc;
+
+use io;
+
+/// Raw file descriptors.
+pub type Fd = libc::c_int;
+
+/// Extract raw file descriptor
+pub trait AsRawFd {
+    /// Extract the raw file descriptor, without taking any ownership.
+    fn as_raw_fd(&self) -> Fd;
+}
+
+impl AsRawFd for io::fs::File {
+    fn as_raw_fd(&self) -> Fd {
+        self.as_inner().fd()
+    }
+}
+
+impl AsRawFd for io::pipe::PipeStream {
+    fn as_raw_fd(&self) -> Fd {
+        self.as_inner().fd()
+    }
+}
+
+impl AsRawFd for io::net::pipe::UnixStream {
+    fn as_raw_fd(&self) -> Fd {
+        self.as_inner().fd()
+    }
+}
+
+impl AsRawFd for io::net::pipe::UnixListener {
+    fn as_raw_fd(&self) -> Fd {
+        self.as_inner().fd()
+    }
+}
+
+impl AsRawFd for io::net::pipe::UnixAcceptor {
+    fn as_raw_fd(&self) -> Fd {
+        self.as_inner().fd()
+    }
+}
+
+impl AsRawFd for io::net::tcp::TcpStream {
+    fn as_raw_fd(&self) -> Fd {
+        self.as_inner().fd()
+    }
+}
+
+impl AsRawFd for io::net::tcp::TcpListener {
+    fn as_raw_fd(&self) -> Fd {
+        self.as_inner().fd()
+    }
+}
+
+impl AsRawFd for io::net::tcp::TcpAcceptor {
+    fn as_raw_fd(&self) -> Fd {
+        self.as_inner().fd()
+    }
+}
+
+impl AsRawFd for io::net::udp::UdpSocket {
+    fn as_raw_fd(&self) -> Fd {
+        self.as_inner().fd()
+    }
+}
+
+/// A prelude for conveniently writing platform-specific code.
+///
+/// Includes all extension traits, and some important type definitions.
+pub mod prelude {
+    pub use super::{Fd, AsRawFd};
+}
diff --git a/src/libstd/sys/unix/mod.rs b/src/libstd/sys/unix/mod.rs
index 7a5317b578d..af238905119 100644
--- a/src/libstd/sys/unix/mod.rs
+++ b/src/libstd/sys/unix/mod.rs
@@ -33,6 +33,7 @@ macro_rules! helper_init( (static $name:ident: Helper<$m:ty>) => (
 ) )
 
 pub mod c;
+pub mod ext;
 pub mod fs;
 pub mod helper_signal;
 pub mod os;
diff --git a/src/libstd/sys/unix/pipe.rs b/src/libstd/sys/unix/pipe.rs
index 4d3469a9c24..3f70fb5c1a5 100644
--- a/src/libstd/sys/unix/pipe.rs
+++ b/src/libstd/sys/unix/pipe.rs
@@ -133,7 +133,7 @@ impl UnixStream {
         }
     }
 
-    fn fd(&self) -> fd_t { self.inner.fd }
+    pub fn fd(&self) -> fd_t { self.inner.fd }
 
     #[cfg(target_os = "linux")]
     fn lock_nonblocking(&self) {}
@@ -222,7 +222,7 @@ impl UnixListener {
         })
     }
 
-    fn fd(&self) -> fd_t { self.inner.fd }
+    pub fn fd(&self) -> fd_t { self.inner.fd }
 
     pub fn listen(self) -> IoResult<UnixAcceptor> {
         match unsafe { libc::listen(self.fd(), 128) } {
@@ -260,7 +260,7 @@ struct AcceptorInner {
 }
 
 impl UnixAcceptor {
-    fn fd(&self) -> fd_t { self.inner.listener.fd() }
+    pub fn fd(&self) -> fd_t { self.inner.listener.fd() }
 
     pub fn accept(&mut self) -> IoResult<UnixStream> {
         let deadline = if self.deadline == 0 {None} else {Some(self.deadline)};
diff --git a/src/libstd/sys/unix/process.rs b/src/libstd/sys/unix/process.rs
index 81bc138ca91..76c316076f9 100644
--- a/src/libstd/sys/unix/process.rs
+++ b/src/libstd/sys/unix/process.rs
@@ -24,7 +24,7 @@ use hash::Hash;
 use sys::{mod, retry, c, wouldblock, set_nonblocking, ms_to_timeval};
 use sys::fs::FileDesc;
 use sys_common::helper_thread::Helper;
-use sys_common::{AsFileDesc, mkerr_libc, timeout};
+use sys_common::{AsInner, mkerr_libc, timeout};
 
 pub use sys_common::ProcessConfig;
 
@@ -56,7 +56,7 @@ impl Process {
     pub fn spawn<K, V, C, P>(cfg: &C, in_fd: Option<P>,
                               out_fd: Option<P>, err_fd: Option<P>)
                               -> IoResult<Process>
-        where C: ProcessConfig<K, V>, P: AsFileDesc,
+        where C: ProcessConfig<K, V>, P: AsInner<FileDesc>,
               K: BytesContainer + Eq + Hash, V: BytesContainer
     {
         use libc::funcs::posix88::unistd::{fork, dup2, close, chdir, execvp};
@@ -183,7 +183,7 @@ impl Process {
                             libc::open(devnull.as_ptr(), flags, 0)
                         }
                         Some(obj) => {
-                            let fd = obj.as_fd().fd();
+                            let fd = obj.as_inner().fd();
                             // Leak the memory and the file descriptor. We're in the
                             // child now an all our resources are going to be
                             // cleaned up very soon
diff --git a/src/libstd/sys/windows/ext.rs b/src/libstd/sys/windows/ext.rs
new file mode 100644
index 00000000000..2c58ee69e8b
--- /dev/null
+++ b/src/libstd/sys/windows/ext.rs
@@ -0,0 +1,100 @@
+// Copyright 2014 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! Experimental extensions to `std` for Windows.
+//!
+//! For now, this module is limited to extracting handles, file
+//! descriptors, and sockets, but its functionality will grow over
+//! time.
+
+#![experimental]
+
+use sys_common::AsInner;
+use libc;
+
+use io;
+
+/// Raw HANDLEs.
+pub type Handle = libc::HANDLE;
+
+/// Raw SOCKETs.
+pub type Socket = libc::SOCKET;
+
+/// Extract raw handles.
+pub trait AsRawHandle {
+    /// Extract the raw handle, without taking any ownership.
+    fn as_raw_handle(&self) -> Handle;
+}
+
+impl AsRawHandle for io::fs::File {
+    fn as_raw_handle(&self) -> Handle {
+        self.as_inner().handle()
+    }
+}
+
+impl AsRawHandle for io::pipe::PipeStream {
+    fn as_raw_handle(&self) -> Handle {
+        self.as_inner().handle()
+    }
+}
+
+impl AsRawHandle for io::net::pipe::UnixStream {
+    fn as_raw_handle(&self) -> Handle {
+        self.as_inner().handle()
+    }
+}
+
+impl AsRawHandle for io::net::pipe::UnixListener {
+    fn as_raw_handle(&self) -> Handle {
+        self.as_inner().handle()
+    }
+}
+
+impl AsRawHandle for io::net::pipe::UnixAcceptor {
+    fn as_raw_handle(&self) -> Handle {
+        self.as_inner().handle()
+    }
+}
+
+/// Extract raw sockets.
+pub trait AsRawSocket {
+    fn as_raw_socket(&self) -> Socket;
+}
+
+impl AsRawSocket for io::net::tcp::TcpStream {
+    fn as_raw_socket(&self) -> Socket {
+        self.as_inner().fd()
+    }
+}
+
+impl AsRawSocket for io::net::tcp::TcpListener {
+    fn as_raw_socket(&self) -> Socket {
+        self.as_inner().fd()
+    }
+}
+
+impl AsRawSocket for io::net::tcp::TcpAcceptor {
+    fn as_raw_socket(&self) -> Socket {
+        self.as_inner().fd()
+    }
+}
+
+impl AsRawSocket for io::net::udp::UdpSocket {
+    fn as_raw_socket(&self) -> Socket {
+        self.as_inner().fd()
+    }
+}
+
+/// A prelude for conveniently writing platform-specific code.
+///
+/// Includes all extension traits, and some important type definitions.
+pub mod prelude {
+    pub use super::{Socket, Handle, AsRawSocket, AsRawHandle};
+}
diff --git a/src/libstd/sys/windows/mod.rs b/src/libstd/sys/windows/mod.rs
index a785ccfe804..6b9555c52ce 100644
--- a/src/libstd/sys/windows/mod.rs
+++ b/src/libstd/sys/windows/mod.rs
@@ -34,6 +34,7 @@ macro_rules! helper_init( (static $name:ident: Helper<$m:ty>) => (
 ) )
 
 pub mod c;
+pub mod ext;
 pub mod fs;
 pub mod helper_signal;
 pub mod os;
diff --git a/src/libstd/sys/windows/pipe.rs b/src/libstd/sys/windows/pipe.rs
index a623c2cd8e2..ca7985aa35b 100644
--- a/src/libstd/sys/windows/pipe.rs
+++ b/src/libstd/sys/windows/pipe.rs
@@ -329,7 +329,7 @@ impl UnixStream {
         }
     }
 
-    fn handle(&self) -> libc::HANDLE { self.inner.handle }
+    pub fn handle(&self) -> libc::HANDLE { self.inner.handle }
 
     fn read_closed(&self) -> bool {
         self.inner.read_closed.load(atomic::SeqCst)
@@ -585,6 +585,10 @@ impl UnixListener {
             }),
         })
     }
+
+    pub fn handle(&self) -> libc::HANDLE {
+        self.handle
+    }
 }
 
 impl Drop for UnixListener {
@@ -729,6 +733,10 @@ impl UnixAcceptor {
             Ok(())
         }
     }
+
+    pub fn handle(&self) -> libc::HANDLE {
+        self.listener.handle()
+    }
 }
 
 impl Clone for UnixAcceptor {
diff --git a/src/libstd/sys/windows/process.rs b/src/libstd/sys/windows/process.rs
index 3fb5ee34356..eddb89c673d 100644
--- a/src/libstd/sys/windows/process.rs
+++ b/src/libstd/sys/windows/process.rs
@@ -26,7 +26,7 @@ use sys::fs;
 use sys::{mod, retry, c, wouldblock, set_nonblocking, ms_to_timeval, timer};
 use sys::fs::FileDesc;
 use sys_common::helper_thread::Helper;
-use sys_common::{AsFileDesc, mkerr_libc, timeout};
+use sys_common::{AsInner, mkerr_libc, timeout};
 
 use io::fs::PathExtensions;
 use string::String;
@@ -105,7 +105,7 @@ impl Process {
     pub fn spawn<K, V, C, P>(cfg: &C, in_fd: Option<P>,
                               out_fd: Option<P>, err_fd: Option<P>)
                               -> IoResult<Process>
-        where C: ProcessConfig<K, V>, P: AsFileDesc,
+        where C: ProcessConfig<K, V>, P: AsInner<FileDesc>,
               K: BytesContainer + Eq + Hash, V: BytesContainer
     {
         use libc::types::os::arch::extra::{DWORD, HANDLE, STARTUPINFO};
@@ -195,7 +195,7 @@ impl Process {
                         }
                     }
                     Some(ref fd) => {
-                        let orig = get_osfhandle(fd.as_fd().fd()) as HANDLE;
+                        let orig = get_osfhandle(fd.as_inner().fd()) as HANDLE;
                         if orig == INVALID_HANDLE_VALUE {
                             return Err(super::last_error())
                         }