Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify the behavior of UDP sockets wrt. multiple addresses in connect #44388

Merged
merged 1 commit into from
Sep 15, 2017
Merged

Clarify the behavior of UDP sockets wrt. multiple addresses in connect #44388

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 9 additions & 16 deletions src/libstd/net/udp.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -586,8 +586,11 @@ impl UdpSocket {
/// 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
/// each of the addresses until the underlying OS function returns no
/// error. Note that usually, a successful `connect` call does not specify
/// that there is a remote server listening on the port, rather, such an
/// error would only be detected after the first send. If the OS returns an
/// error for each of the specified addresses, the error returned from the
/// last connection attempt (the last address) is returned.
///
/// # Examples
Expand All @@ -602,20 +605,10 @@ impl UdpSocket {
/// 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");
/// ```
/// Unlike in the TCP case, passing an array of addresses to the `connect`
/// function of a UDP socket is not a useful thing to do: The OS will be
/// unable to determine whether something is listening on the remote
/// address without the application sending data.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

since this is no longer associated with an example, seems like we can move this paragraph above the # Examples heading. what do you think?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My rationale for leaving it there was that this explanation is in a similar spot for the other methods and also in TcpStream. But I guess I can move it up.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, the text is already up there. It's just summarized in the examples because there's usually an example of using multiple addresses.

#[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))
Expand Down