Comments

diff --git a/client.go b/client.go
index 27af8fc705d8e1b60b8e95c08e990985bfe97411..ee15ee0fb7164fe31f14d1f904ba3408e3009f72 100644 (file)
--- a/client.go
+++ b/client.go
@@ -1975,6 +1975,7 @@ func (t Torrent) Files() (ret []File) {
        return
 }
 
+// Marks the pieces in the given region for download.
 func (t Torrent) SetRegionPriority(off, len int64) {
        t.cl.mu.Lock()
        defer t.cl.mu.Unlock()

diff --git a/connection.go b/connection.go
index ed94626ff3a890b1b0d1242045374fa0708f548c..1bf69b15f7b6c9b68fafe459778ffe75b6d1fa13 100644 (file)
--- a/connection.go
+++ b/connection.go
@@ -39,7 +39,8 @@ type connection struct {
        post      chan pp.Message
        writeCh   chan []byte
 
-       // The connections preferred order to download pieces.
+       // The connection's preferred order to download pieces. The index is the
+       // piece, the value is its priority.
        piecePriorities []int
        // The piece request order based on piece priorities.
        pieceRequestOrder *pieceordering.Instance
@@ -109,6 +110,7 @@ func (cn *connection) pendPiece(piece int, priority piecePriority) {
        // Priority regions not to scale. Within each region, piece is randomized
        // according to connection.
 
+       // <-request first -- last->
        // [ Now         ]
        //  [ Next       ]
        //   [ Readahead ]

diff --git a/internal/pieceordering/pieceordering.go b/internal/pieceordering/pieceordering.go
index d26cbdcd2d1b55ae09254be760e74fc1d08e48a8..169ebbc7ee2ef50356c7d679ff14ffdb5fa0690f 100644 (file)
--- a/internal/pieceordering/pieceordering.go
+++ b/internal/pieceordering/pieceordering.go
@@ -10,7 +10,11 @@ import (
 
 // Maintains piece integers by their ascending assigned keys.
 type Instance struct {
-       sl        *skiplist.SkipList
+       // Contains the ascending priority keys. The keys contain a slice of piece
+       // indices.
+       sl *skiplist.SkipList
+       // Maps from piece index back to its key, so that it can be remove
+       // efficiently from the skip list.
        pieceKeys map[int]int
 }
 
@@ -41,6 +45,7 @@ func (me *Instance) SetPiece(piece, key int) {
        me.shuffleItem(key)
 }
 
+// Shuffle the piece indices that share a given key.
 func (me *Instance) shuffleItem(key int) {
        _item, ok := me.sl.Get(key)
        if !ok {

diff --git a/piece.go b/piece.go
index 6bb96a3e69b428cf9b2535ec881b0e4ceef43d76..c45e7a423bedbe99b318362b268b675ea0faaeb2 100644 (file)
--- a/piece.go
+++ b/piece.go
@@ -7,6 +7,8 @@ import (
        pp "github.com/anacrolix/torrent/peer_protocol"
 )
 
+// Piece priority describes the importance of obtaining a particular piece.
+
 type piecePriority byte
 
 const (
@@ -18,8 +20,8 @@ const (
 )
 
 type piece struct {
-       Hash pieceSum
-       // Chunks we don't have. The offset and length can be determined by our
+       Hash pieceSum // The completed piece SHA1 hash, from the metainfo "pieces" field.
+       // Chunks we don't have. The offset and length can be determined by the
        // request chunkSize in use.
        PendingChunkSpecs []bool
        Hashing           bool