mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Expand docs of multi-address behavior of some UDP/TCP APIs.

Browse Source 
Fixes https://github.com/rust-lang/rust/issues/22569.
This commit is contained in:
Corey Farwell 2017-08-30 22:11:48 -04:00
parent 7eeac1b814
commit 0a716fdce2
2 changed files with 92 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
src/libstd/net/tcp.rs
View File

@ -111,15 +111,18 @@ impl TcpStream {
/// `addr` is an address of the remote host. Anything which implements
/// [`ToSocketAddrs`] trait can be supplied for the address; see this trait
/// documentation for concrete examples.
/// In case [`ToSocketAddrs::to_socket_addrs()`] returns more than one entry,
/// then the first valid and reachable address is used.
///
/// If `addr` yields multiple addresses, `connect` will be attempted with
/// each of the addresses until a connection is successful. If none of
/// the addresses result in a successful connection, the error returned from
/// the last connection attempt (the last address) is returned.
///
/// [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html
/// [`ToSocketAddrs::to_socket_addrs()`]:
/// ../../std/net/trait.ToSocketAddrs.html#tymethod.to_socket_addrs
///
/// # Examples
///
/// Open a TCP connection to `127.0.0.1:8080`:
///
/// ```no_run
/// use std::net::TcpStream;
///
@ -129,6 +132,23 @@ impl TcpStream {
/// println!("Couldn't connect to server...");
/// }
/// ```
///
/// Open a TCP connection to `127.0.0.1:8080`. If the connection fails, open
/// a TCP connection to `127.0.0.1:8081`:
///
/// ```no_run
/// use std::net::{SocketAddr, TcpStream};
///
/// let addrs = [
/// SocketAddr::from(([127, 0, 0, 1], 8080)),
/// SocketAddr::from(([127, 0, 0, 1], 8081)),
/// ];
/// if let Ok(stream) = TcpStream::connect(&addrs[..]) {
/// println!("Connected to the server!");
/// } else {
/// println!("Couldn't connect to server...");
/// }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn connect<A: ToSocketAddrs>(addr: A) -> io::Result<TcpStream> {
super::each_addr(addr, net_imp::TcpStream::connect).map(TcpStream)
@ -557,16 +577,36 @@ impl TcpListener {
/// The address type can be any implementor of [`ToSocketAddrs`] trait. See
/// its documentation for concrete examples.
///
/// If `addr` yields multiple addresses, `bind` will be attempted with
/// each of the addresses until one succeeds and returns the listener. If
/// none of the addresses succeed in creating a listener, the error returned
/// from the last attempt (the last address) is returned.
///
/// [`local_addr`]: #method.local_addr
/// [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html
///
/// # Examples
///
/// Create a TCP listener bound to `127.0.0.1:80`:
///
/// ```no_run
/// use std::net::TcpListener;
///
/// let listener = TcpListener::bind("127.0.0.1:80").unwrap();
/// ```
///
/// Create a TCP listener bound to `127.0.0.1:80`. If that fails, create a
/// TCP listener bound to `127.0.0.1:443`:
///
/// ```no_run
/// use std::net::{SocketAddr, TcpListener};
///
/// let addrs = [
/// SocketAddr::from(([127, 0, 0, 1], 80)),
/// SocketAddr::from(([127, 0, 0, 1], 443)),
/// ];
/// let listener = TcpListener::bind(&addrs[..]).unwrap();
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn bind<A: ToSocketAddrs>(addr: A) -> io::Result<TcpListener> {
super::each_addr(addr, net_imp::TcpListener::bind).map(TcpListener)

50
src/libstd/net/udp.rs
View File

@ -69,14 +69,34 @@ impl UdpSocket {
/// The address type can be any implementor of [`ToSocketAddrs`] trait. See
/// its documentation for concrete examples.
///
/// If `addr` yields multiple addresses, `bind` will be attempted with
/// each of the addresses until one succeeds and returns the socket. If none
/// of the addresses succeed in creating a socket, the error returned from
/// the last attempt (the last address) is returned.
///
/// [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html
///
/// # Examples
///
/// Create a UDP socket bound to `127.0.0.1:3400`:
///
/// ```no_run
/// use std::net::UdpSocket;
///
/// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
/// let socket = UdpSocket::bind("127.0.0.1:3400").expect("couldn't bind to address");
/// ```
///
/// Create a UDP socket bound to `127.0.0.1:3400`. If the socket cannot be
/// bound to that address, create a UDP socket bound to `127.0.0.1:3401`:
///
/// ```no_run
/// use std::net::{SocketAddr, UdpSocket};
///
/// let addrs = [
/// SocketAddr::from(([127, 0, 0, 1], 3400)),
/// SocketAddr::from(([127, 0, 0, 1], 3401)),
/// ];
/// let socket = UdpSocket::bind(&addrs[..]).expect("couldn't bind to address");
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn bind<A: ToSocketAddrs>(addr: A) -> io::Result<UdpSocket> {
@ -130,6 +150,9 @@ pub fn peek_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> {
/// Address type can be any implementor of [`ToSocketAddrs`] trait. See its
/// documentation for concrete examples.
///
/// It is possible for `addr` to yield multiple addresses, but `send_to`
/// will only send data to the first address yielded by `addr`.
///
/// This will return an error when the IP version of the local socket
/// does not match that returned from [`ToSocketAddrs`].
///
@ -562,14 +585,37 @@ pub fn take_error(&self) -> io::Result<Option<io::Error>> {
/// `recv` syscalls to be used to send data and also applies filters to only
/// receive data from the specified address.
///
/// If `addr` yields multiple addresses, `connect` will be attempted with
/// each of the addresses until a connection is successful. If none of
/// the addresses are able to be connected, the error returned from the
/// last connection attempt (the last address) is returned.
///
/// # Examples
///
/// Create a UDP socket bound to `127.0.0.1:3400` and connect the socket to
/// `127.0.0.1:8080`:
///
/// ```no_run
/// use std::net::UdpSocket;
///
/// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
/// let socket = UdpSocket::bind("127.0.0.1:3400").expect("couldn't bind to address");
/// socket.connect("127.0.0.1:8080").expect("connect function failed");
/// ```
///
/// Create a UDP socket bound to `127.0.0.1:3400` and connect the socket to
/// `127.0.0.1:8080`. If that connection fails, then the UDP socket will
/// connect to `127.0.0.1:8081`:
///
/// ```no_run
/// use std::net::{SocketAddr, UdpSocket};
///
/// let socket = UdpSocket::bind("127.0.0.1:3400").expect("couldn't bind to address");
/// let connect_addrs = [
/// SocketAddr::from(([127, 0, 0, 1], 8080)),
/// SocketAddr::from(([127, 0, 0, 1], 8081)),
/// ];
/// socket.connect(&connect_addrs[..]).expect("connect function failed");
/// ```
#[stable(feature = "net2_mutators", since = "1.9.0")]
pub fn connect<A: ToSocketAddrs>(&self, addr: A) -> io::Result<()> {
super::each_addr(addr, |addr| self.0.connect(addr))