async_std/os/unix/net/
stream.rs

1//! Unix-specific networking extensions.
2
3use std::fmt;
4use std::io::{Read as _, Write as _};
5use std::net::Shutdown;
6use std::pin::Pin;
7
8use mio_uds;
9
10use super::SocketAddr;
11use crate::io::{self, Read, Write};
12use crate::net::driver::Watcher;
13use crate::os::unix::io::{AsRawFd, FromRawFd, IntoRawFd, RawFd};
14use crate::path::Path;
15use crate::task::{spawn_blocking, Context, Poll};
16
17/// A Unix stream socket.
18///
19/// This type is an async version of [`std::os::unix::net::UnixStream`].
20///
21/// [`std::os::unix::net::UnixStream`]:
22/// https://doc.rust-lang.org/std/os/unix/net/struct.UnixStream.html
23///
24/// # Examples
25///
26/// ```no_run
27/// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
28/// #
29/// use async_std::os::unix::net::UnixStream;
30/// use async_std::prelude::*;
31///
32/// let mut stream = UnixStream::connect("/tmp/socket").await?;
33/// stream.write_all(b"hello world").await?;
34///
35/// let mut response = Vec::new();
36/// stream.read_to_end(&mut response).await?;
37/// #
38/// # Ok(()) }) }
39/// ```
40pub struct UnixStream {
41    pub(super) watcher: Watcher<mio_uds::UnixStream>,
42}
43
44impl UnixStream {
45    /// Connects to the socket to the specified address.
46    ///
47    /// # Examples
48    ///
49    /// ```no_run
50    /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
51    /// #
52    /// use async_std::os::unix::net::UnixStream;
53    ///
54    /// let stream = UnixStream::connect("/tmp/socket").await?;
55    /// #
56    /// # Ok(()) }) }
57    /// ```
58    pub async fn connect<P: AsRef<Path>>(path: P) -> io::Result<UnixStream> {
59        let path = path.as_ref().to_owned();
60
61        spawn_blocking(move || {
62            let std_stream = std::os::unix::net::UnixStream::connect(path)?;
63            let mio_stream = mio_uds::UnixStream::from_stream(std_stream)?;
64            Ok(UnixStream {
65                watcher: Watcher::new(mio_stream),
66            })
67        })
68        .await?
69    }
70
71    /// Creates an unnamed pair of connected sockets.
72    ///
73    /// Returns two streams which are connected to each other.
74    ///
75    /// # Examples
76    ///
77    /// ```no_run
78    /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
79    /// #
80    /// use async_std::os::unix::net::UnixStream;
81    ///
82    /// let stream = UnixStream::pair()?;
83    /// #
84    /// # Ok(()) }) }
85    /// ```
86    pub fn pair() -> io::Result<(UnixStream, UnixStream)> {
87        let (a, b) = mio_uds::UnixStream::pair()?;
88        let a = UnixStream {
89            watcher: Watcher::new(a),
90        };
91        let b = UnixStream {
92            watcher: Watcher::new(b),
93        };
94        Ok((a, b))
95    }
96
97    /// Returns the socket address of the local half of this connection.
98    ///
99    /// # Examples
100    ///
101    /// ```no_run
102    /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
103    /// #
104    /// use async_std::os::unix::net::UnixStream;
105    ///
106    /// let stream = UnixStream::connect("/tmp/socket").await?;
107    /// let addr = stream.local_addr()?;
108    /// #
109    /// # Ok(()) }) }
110    /// ```
111    pub fn local_addr(&self) -> io::Result<SocketAddr> {
112        self.watcher.get_ref().local_addr()
113    }
114
115    /// Returns the socket address of the remote half of this connection.
116    ///
117    /// # Examples
118    ///
119    /// ```no_run
120    /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
121    /// #
122    /// use async_std::os::unix::net::UnixStream;
123    ///
124    /// let stream = UnixStream::connect("/tmp/socket").await?;
125    /// let peer = stream.peer_addr()?;
126    /// #
127    /// # Ok(()) }) }
128    /// ```
129    pub fn peer_addr(&self) -> io::Result<SocketAddr> {
130        self.watcher.get_ref().peer_addr()
131    }
132
133    /// Shuts down the read, write, or both halves of this connection.
134    ///
135    /// This function will cause all pending and future I/O calls on the specified portions to
136    /// immediately return with an appropriate value (see the documentation of [`Shutdown`]).
137    ///
138    /// [`Shutdown`]: https://doc.rust-lang.org/std/net/enum.Shutdown.html
139    ///
140    /// ```no_run
141    /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
142    /// #
143    /// use async_std::os::unix::net::UnixStream;
144    /// use std::net::Shutdown;
145    ///
146    /// let stream = UnixStream::connect("/tmp/socket").await?;
147    /// stream.shutdown(Shutdown::Both)?;
148    /// #
149    /// # Ok(()) }) }
150    /// ```
151    pub fn shutdown(&self, how: Shutdown) -> io::Result<()> {
152        self.watcher.get_ref().shutdown(how)
153    }
154}
155
156impl Read for UnixStream {
157    fn poll_read(
158        self: Pin<&mut Self>,
159        cx: &mut Context<'_>,
160        buf: &mut [u8],
161    ) -> Poll<io::Result<usize>> {
162        Pin::new(&mut &*self).poll_read(cx, buf)
163    }
164}
165
166impl Read for &UnixStream {
167    fn poll_read(
168        self: Pin<&mut Self>,
169        cx: &mut Context<'_>,
170        buf: &mut [u8],
171    ) -> Poll<io::Result<usize>> {
172        self.watcher.poll_read_with(cx, |mut inner| inner.read(buf))
173    }
174}
175
176impl Write for UnixStream {
177    fn poll_write(
178        self: Pin<&mut Self>,
179        cx: &mut Context<'_>,
180        buf: &[u8],
181    ) -> Poll<io::Result<usize>> {
182        Pin::new(&mut &*self).poll_write(cx, buf)
183    }
184
185    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
186        Pin::new(&mut &*self).poll_flush(cx)
187    }
188
189    fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
190        Pin::new(&mut &*self).poll_close(cx)
191    }
192}
193
194impl Write for &UnixStream {
195    fn poll_write(
196        self: Pin<&mut Self>,
197        cx: &mut Context<'_>,
198        buf: &[u8],
199    ) -> Poll<io::Result<usize>> {
200        self.watcher
201            .poll_write_with(cx, |mut inner| inner.write(buf))
202    }
203
204    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
205        self.watcher.poll_write_with(cx, |mut inner| inner.flush())
206    }
207
208    fn poll_close(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<io::Result<()>> {
209        Poll::Ready(Ok(()))
210    }
211}
212
213impl fmt::Debug for UnixStream {
214    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
215        let mut builder = f.debug_struct("UnixStream");
216        builder.field("fd", &self.as_raw_fd());
217
218        if let Ok(addr) = self.local_addr() {
219            builder.field("local", &addr);
220        }
221
222        if let Ok(addr) = self.peer_addr() {
223            builder.field("peer", &addr);
224        }
225
226        builder.finish()
227    }
228}
229
230impl From<std::os::unix::net::UnixStream> for UnixStream {
231    /// Converts a `std::os::unix::net::UnixStream` into its asynchronous equivalent.
232    fn from(stream: std::os::unix::net::UnixStream) -> UnixStream {
233        let mio_stream = mio_uds::UnixStream::from_stream(stream).unwrap();
234        UnixStream {
235            watcher: Watcher::new(mio_stream),
236        }
237    }
238}
239
240impl AsRawFd for UnixStream {
241    fn as_raw_fd(&self) -> RawFd {
242        self.watcher.get_ref().as_raw_fd()
243    }
244}
245
246impl FromRawFd for UnixStream {
247    unsafe fn from_raw_fd(fd: RawFd) -> UnixStream {
248        let stream = std::os::unix::net::UnixStream::from_raw_fd(fd);
249        stream.into()
250    }
251}
252
253impl IntoRawFd for UnixStream {
254    fn into_raw_fd(self) -> RawFd {
255        self.watcher.into_inner().into_raw_fd()
256    }
257}
async_std/os/unix/net/stream.rs

async_std/os/unix/net/
stream.rs
