mathieu/os-rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rollup merge of #83524 - faern:document-socketaddr-mem-layout, r=sfackler

Browse source 
Document that the SocketAddr memory representation is not stable

Intended to help out with #78802. Work has been put into finding and fixing code that assumes the memory layout of `SocketAddrV4` and `SocketAddrV6`. But it turns out there are cases where new code continues to make the same assumption ([example](96927dc2b7 (diff-917db3d8ca6f862ebf42726b23c72a12b35e584e497ebdb24e474348d7c6ffb6R610-R621))).

The memory layout of a type in `std` is never part of the public API. Unless explicitly stated I guess. But since that is invalidly relied upon by a considerable amount of code for these particular types, it might make sense to explicitly document this. This can be temporary. Once #78802 lands it does not make sense to rely on the layout any longer, and this documentation can also be removed.
This commit is contained in:
Yuki Okushi 2021-03-27 12:37:24 +09:00 • committed by GitHub
commit d340f63cca
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 8 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
library/std/src/net/addr.rs
View file

@ -57,7 +57,8 @@ pub enum SocketAddr {
/// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses.
///
/// The size of a `SocketAddrV4` struct may vary depending on the target operating
/// system.
/// system. Do not assume that this type has the same memory layout as the underlying
/// system representation.
///
/// [IETF RFC 793]: https://tools.ietf.org/html/rfc793
/// [`IPv4` address]: Ipv4Addr
@ -76,6 +77,8 @@ pub enum SocketAddr {
#[derive(Copy)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct SocketAddrV4 {
// Do not assume that this struct is implemented as the underlying system representation.
// The memory layout is not part of the stable interface that std exposes.
inner: c::sockaddr_in,
}
@ -88,7 +91,8 @@ pub struct SocketAddrV4 {
/// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses.
///
/// The size of a `SocketAddrV6` struct may vary depending on the target operating
/// system.
/// system. Do not assume that this type has the same memory layout as the underlying
/// system representation.
///
/// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
/// [`IPv6` address]: Ipv6Addr
@ -107,6 +111,8 @@ pub struct SocketAddrV4 {
#[derive(Copy)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct SocketAddrV6 {
// Do not assume that this struct is implemented as the underlying system representation.
// The memory layout is not part of the stable interface that std exposes.
inner: c::sockaddr_in6,
}