From: Matt Joiner <anacrolix@gmail.com>
Date: Mon, 16 Mar 2020 05:30:39 +0000 (+1100)
Subject: Add doc comments related to #383
X-Git-Tag: v1.15.0~8
X-Git-Url: http://www.git.stargrave.org/?a=commitdiff_plain;h=4a5b891a34af17531596b0ce9c01312ff3498e84;p=btrtrc.git

Add doc comments related to #383
---

diff --git a/conn_stats.go b/conn_stats.go
index 9b0865a0..3fbc00d8 100644
--- a/conn_stats.go
+++ b/conn_stats.go
@@ -10,11 +10,11 @@ import (
 	pp "github.com/anacrolix/torrent/peer_protocol"
 )
 
-// Various connection-level metrics. At the Torrent level these are
-// aggregates. Chunks are messages with data payloads. Data is actual torrent
-// content without any overhead. Useful is something we needed locally.
-// Unwanted is something we didn't ask for (but may still be useful). Written
-// is things sent to the peer, and Read is stuff received from them.
+// Various connection-level metrics. At the Torrent level these are aggregates. Chunks are messages
+// with data payloads. Data is actual torrent content without any overhead. Useful is something we
+// needed locally. Unwanted is something we didn't ask for (but may still be useful). Written is
+// things sent to the peer, and Read is stuff received from them. Due to the implementation of
+// Count, must be aligned on some platforms: See https://github.com/anacrolix/torrent/issues/262.
 type ConnStats struct {
 	// Total bytes on the wire. Includes handshakes and encryption.
 	BytesWritten     Count
diff --git a/torrent.go b/torrent.go
index 42f5636e..bcd80637 100644
--- a/torrent.go
+++ b/torrent.go
@@ -1395,6 +1395,8 @@ func (t *Torrent) addPeers(peers []Peer) {
 	}
 }
 
+// The returned TorrentStats may require alignment in memory. See
+// https://github.com/anacrolix/torrent/issues/383.
 func (t *Torrent) Stats() TorrentStats {
 	t.cl.rLock()
 	defer t.cl.rUnlock()
diff --git a/torrent_stats.go b/torrent_stats.go
index edc4ac8e..bc54e1bd 100644
--- a/torrent_stats.go
+++ b/torrent_stats.go
@@ -1,8 +1,10 @@
 package torrent
 
+// Due to ConnStats, may require special alignment on some platforms. See
+// https://github.com/anacrolix/torrent/issues/383.
 type TorrentStats struct {
-	// Aggregates stats over all connections past and present. Some values may
-	// not have much meaning in the aggregate context.
+	// Aggregates stats over all connections past and present. Some values may not have much meaning
+	// in the aggregate context.
 	ConnStats
 
 	// Ordered by expected descending quantities (if all is well).