librats 1.0.2 → 2.2.0

package/native-src/src/librats/bittorrent/piece_picker.cpp

@@ -0,0 +1,352 @@
+#include "librats/bittorrent/piece_picker.h"
+#include "librats/bittorrent/log.h"
+#include "librats/bittorrent/types.h"  // kBlockSize
+
+#include <algorithm>
+
+namespace librats::bittorrent {
+
+PiecePicker::PiecePicker(std::uint32_t num_pieces, std::uint32_t piece_length, std::int64_t total_size)
+    : num_pieces_(num_pieces)
+    , piece_length_(piece_length)
+    , total_size_(total_size)
+    , availability_(num_pieces, 0)
+    , priority_(num_pieces, PiecePriority::Normal)
+    , have_(num_pieces, false)
+    , pieces_left_(num_pieces)
+    , order_pos_(num_pieces, 0)
+    , in_order_(num_pieces, 0)
+    , rng_(std::random_device{}()) {
+    // Every piece starts wanted (Normal priority, not-have, availability 0), so it
+    // all begins life in the single bucket {Normal, 0}.
+    for (std::uint32_t p = 0; p < num_pieces_; ++p) order_insert(p);
+}
+
+// ---- geometry ----
+
+std::uint32_t PiecePicker::piece_size(std::uint32_t piece) const noexcept {
+    if (piece + 1 < num_pieces_) return piece_length_;
+    const std::int64_t tail = total_size_ - std::int64_t(piece) * piece_length_;
+    if (tail <= 0) return 0;
+    return std::uint32_t(std::min<std::int64_t>(tail, piece_length_));
+}
+
+std::uint32_t PiecePicker::blocks_in_piece(std::uint32_t piece) const noexcept {
+    return (piece_size(piece) + kBlockSize - 1) / kBlockSize;
+}
+
+std::uint32_t PiecePicker::block_size(std::uint32_t piece, std::uint32_t block) const noexcept {
+    const std::uint32_t ps = piece_size(piece);
+    const std::uint32_t off = block * kBlockSize;
+    return (std::min)(kBlockSize, ps - off);
+}
+
+// ---- our progress ----
+
+void PiecePicker::we_have(std::uint32_t piece) {
+    if (have_.get(piece)) return;
+    order_remove(piece);  // no longer wanted — pull it out of the rarest index
+    have_.set(piece);
+    ++num_have_;
+    if (priority_[piece] != PiecePriority::DontDownload && pieces_left_ > 0) --pieces_left_;
+    downloading_.erase(piece);
+    // Advance the sequential cursor over any now-contiguous prefix of have pieces.
+    while (seq_cursor_ < num_pieces_ && have_.get(seq_cursor_)) ++seq_cursor_;
+}
+
+void PiecePicker::we_have_all() {
+    for (std::uint32_t p = 0; p < num_pieces_; ++p) we_have(p);
+}
+
+void PiecePicker::set_have_bitfield(const Bitfield& have) {
+    for (std::uint32_t p = 0; p < num_pieces_; ++p)
+        if (have.size() > p && have.get(p)) we_have(p);
+}
+
+// ---- priorities ----
+
+void PiecePicker::set_piece_priority(std::uint32_t piece, PiecePriority priority) {
+    const PiecePriority old = priority_[piece];
+    if (old == priority) return;
+    order_remove(piece);  // remove under the OLD key before the priority changes
+    if (!have_.get(piece)) {
+        const bool was_wanted = old != PiecePriority::DontDownload;
+        const bool now_wanted = priority != PiecePriority::DontDownload;
+        if (was_wanted && !now_wanted) { --pieces_left_; downloading_.erase(piece); }
+        else if (!was_wanted && now_wanted) ++pieces_left_;
+    }
+    priority_[piece] = priority;
+    order_insert(piece);  // re-file under the new key (no-op if it is now unwanted)
+}
+
+// ---- availability ----
+
+void PiecePicker::peer_has_piece(std::uint32_t piece)  { avail_add(piece, +1); }
+void PiecePicker::peer_lost_piece(std::uint32_t piece) { avail_add(piece, -1); }
+void PiecePicker::inc_availability(const Bitfield& peer_have) {
+    for (std::uint32_t p = 0; p < num_pieces_; ++p)
+        if (peer_have.size() > p && peer_have.get(p)) avail_add(p, +1);
+}
+void PiecePicker::dec_availability(const Bitfield& peer_have) {
+    for (std::uint32_t p = 0; p < num_pieces_; ++p)
+        if (peer_have.size() > p && peer_have.get(p)) avail_add(p, -1);
+}
+// A seed has every piece. Bumping every piece's availability (O(n) plus a bucket
+// move each) is wasted work: since a seed shifts *all* pieces equally, the
+// rarest-first ordering is unchanged, so the bucket index (keyed on the per-peer
+// count) needs no update at all. Track seeds as one counter instead — the
+// effective availability of a piece is availability_[p] + seeds_ — making a seed
+// joining or leaving O(1). (Mirrors libtorrent's m_seeds.)
+void PiecePicker::inc_availability_all() { ++seeds_; }
+void PiecePicker::dec_availability_all() { if (seeds_ > 0) --seeds_; }
+
+// ---- block state machine ----
+
+PiecePicker::DownloadingPiece& PiecePicker::downloading_for(std::uint32_t piece) {
+    auto it = downloading_.find(piece);
+    if (it != downloading_.end()) return it->second;
+    DownloadingPiece dp;
+    dp.blocks.resize(blocks_in_piece(piece));
+    return downloading_.emplace(piece, std::move(dp)).first->second;
+}
+
+void PiecePicker::mark_requested(const PieceBlock& b, const void* peer) {
+    DownloadingPiece& dp = downloading_for(b.piece);
+    Block& blk = dp.blocks[b.block];
+    if (blk.state == BlockState::None) {
+        blk.state = BlockState::Requested;
+        ++dp.num_requested;
+    }
+    if (std::find(blk.peers.begin(), blk.peers.end(), peer) == blk.peers.end())
+        blk.peers.push_back(peer);
+}
+
+std::vector<const void*> PiecePicker::mark_writing(const PieceBlock& b, const void* peer) {
+    std::vector<const void*> others;
+    auto it = downloading_.find(b.piece);
+    if (it == downloading_.end()) return others;
+    Block& blk = it->second.blocks[b.block];
+    if (blk.state == BlockState::Requested) {
+        --it->second.num_requested;
+        blk.state = BlockState::Writing;
+        ++it->second.num_writing;
+        // Hand back the *other* requesters (end-game) so the caller can CANCEL the
+        // now-redundant duplicate requests, then drop the requester set — the block
+        // is in flight to disk and must not be picked or re-requested again.
+        for (const void* p : blk.peers)
+            if (p != peer) others.push_back(p);
+        blk.peers.clear();
+    }
+    return others;
+}
+
+bool PiecePicker::mark_finished(const PieceBlock& b) {
+    DownloadingPiece& dp = downloading_for(b.piece);
+    Block& blk = dp.blocks[b.block];
+    if (blk.state == BlockState::Requested) --dp.num_requested;
+    else if (blk.state == BlockState::Writing) --dp.num_writing;
+    if (blk.state != BlockState::Finished) { blk.state = BlockState::Finished; ++dp.num_finished; }
+    blk.peers.clear();
+    return dp.num_finished == dp.blocks.size();
+}
+
+void PiecePicker::abort_block(const PieceBlock& b, const void* peer) {
+    auto it = downloading_.find(b.piece);
+    if (it == downloading_.end()) return;
+    Block& blk = it->second.blocks[b.block];
+    blk.peers.erase(std::remove(blk.peers.begin(), blk.peers.end(), peer), blk.peers.end());
+    if (blk.state == BlockState::Requested && blk.peers.empty()) {
+        blk.state = BlockState::None;
+        --it->second.num_requested;
+    }
+}
+
+void PiecePicker::cancel_peer(const void* peer) {
+    for (auto& [piece, dp] : downloading_) {
+        for (auto& blk : dp.blocks) {
+            blk.peers.erase(std::remove(blk.peers.begin(), blk.peers.end(), peer), blk.peers.end());
+            if (blk.state == BlockState::Requested && blk.peers.empty()) {
+                blk.state = BlockState::None;
+                --dp.num_requested;
+            }
+        }
+    }
+}
+
+void PiecePicker::restore_piece(std::uint32_t piece) {
+    downloading_.erase(piece);  // drop all block progress; piece becomes fresh
+}
+
+BlockState PiecePicker::block_state(std::uint32_t piece, std::uint32_t block) const {
+    if (have_.get(piece)) return BlockState::Finished;
+    auto it = downloading_.find(piece);
+    if (it == downloading_.end()) return BlockState::None;
+    return it->second.blocks[block].state;
+}
+
+bool PiecePicker::is_interesting(const Bitfield& peer_have) const {
+    for (std::uint32_t p = 0; p < num_pieces_; ++p)
+        if (wanted(p) && peer_have.size() > p && peer_have.get(p)) return true;
+    return false;
+}
+
+// ---- picking ----
+
+void PiecePicker::append_free_blocks(std::uint32_t piece, int count, const void* peer,
+                                     std::vector<PieceBlock>& out) const {
+    const std::uint32_t nblocks = blocks_in_piece(piece);
+    auto it = downloading_.find(piece);
+    for (std::uint32_t b = 0; b < nblocks && int(out.size()) < count; ++b) {
+        if (it == downloading_.end() || it->second.blocks[b].state == BlockState::None)
+            out.push_back(PieceBlock{piece, b});
+    }
+}
+
+void PiecePicker::order_insert(std::uint32_t piece) {
+    if (in_order_[piece] || !wanted(piece)) return;
+    std::vector<std::vector<std::uint32_t>>& col = buckets_[prio_idx(priority_[piece])];
+    const std::uint32_t av = availability_[piece];
+    if (col.size() <= av) col.resize(av + 1);   // grow the availability dimension on demand
+    std::vector<std::uint32_t>& bucket = col[av];
+    order_pos_[piece] = std::uint32_t(bucket.size());
+    bucket.push_back(piece);
+    in_order_[piece] = 1;
+}
+
+void PiecePicker::order_remove(std::uint32_t piece) {
+    if (!in_order_[piece]) return;
+    // Bucket coords must match the ones used at insert — callers remove *before*
+    // mutating priority_/availability_ (see avail_add / set_piece_priority).
+    std::vector<std::uint32_t>& bucket = buckets_[prio_idx(priority_[piece])][availability_[piece]];
+    const std::uint32_t pos  = order_pos_[piece];
+    const std::uint32_t last = bucket.back();
+    bucket[pos] = last;            // swap the tail piece into the vacated slot...
+    order_pos_[last] = pos;        // ...and fix up its recorded position
+    bucket.pop_back();             // empty buckets simply stay empty — no alloc churn
+    in_order_[piece] = 0;
+}
+
+void PiecePicker::avail_add(std::uint32_t piece, int delta) {
+    // Remove under the current key, change availability, then re-file under the new
+    // key — an O(log n) bucket move. (For a have/unwanted piece the index ops are
+    // no-ops; we still track its availability count.)
+    order_remove(piece);
+    if (delta >= 0) {
+        availability_[piece] += std::uint32_t(delta);
+    } else {
+        const std::uint32_t d = std::uint32_t(-delta);
+        availability_[piece] = availability_[piece] > d ? availability_[piece] - d : 0;
+    }
+    order_insert(piece);
+}
+
+std::vector<PieceBlock> PiecePicker::pick_blocks(const Bitfield& peer_have, int count, const void* peer) {
+    std::vector<PieceBlock> result;
+    if (count <= 0) return result;
+
+    auto peer_has = [&](std::uint32_t p) { return peer_have.size() > p && peer_have.get(p); };
+
+    // 1) Finish pieces already in progress that this peer can serve. In sequential
+    // mode finish the earliest partial first (streaming order); otherwise the map
+    // order is fine. (downloading_ is small — bounded by peers × pieces-in-flight.)
+    auto take_partial = [&](std::uint32_t piece) {
+        if (int(result.size()) >= count) return;
+        if (!wanted(piece) || !peer_has(piece)) return;
+        append_free_blocks(piece, count, peer, result);
+    };
+    if (mode_ == PickMode::Sequential) {
+        std::vector<std::uint32_t> partials;
+        partials.reserve(downloading_.size());
+        for (const auto& kv : downloading_) partials.push_back(kv.first);
+        std::sort(partials.begin(), partials.end());
+        for (std::uint32_t piece : partials) {
+            if (int(result.size()) >= count) break;
+            take_partial(piece);
+        }
+    } else {
+        for (const auto& [piece, dp] : downloading_) {
+            if (int(result.size()) >= count) break;
+            take_partial(piece);
+        }
+    }
+    if (int(result.size()) >= count) return result;
+
+    // 2) Start new pieces, ordered by the active strategy.
+    auto try_new_piece = [&](std::uint32_t p) {
+        if (!wanted(p) || !peer_has(p) || downloading_.count(p)) return;
+        append_free_blocks(p, count, peer, result);
+    };
+    switch (mode_) {
+        case PickMode::Sequential:
+            // Start at the cursor: every piece below it is already have, so there
+            // is nothing to pick there. This keeps the hot refill path off the
+            // completed prefix instead of rescanning it from 0 every time.
+            for (std::uint32_t p = seq_cursor_; p < num_pieces_ && int(result.size()) < count; ++p)
+                try_new_piece(p);
+            break;
+        case PickMode::Random: {
+            // Walk the rarest-first buckets — which already hold exactly the wanted
+            // pieces — in a shuffled order, each entered at a random offset. That is
+            // a random spread without scanning or allocating across all pieces (the
+            // bucket set is small: one per distinct (priority, availability)).
+            std::vector<std::vector<std::uint32_t>*> bkts;
+            for (auto& col : buckets_)
+                for (auto& bucket : col)
+                    if (!bucket.empty()) bkts.push_back(&bucket);
+            std::shuffle(bkts.begin(), bkts.end(), rng_);
+            for (auto* bucket : bkts) {
+                if (int(result.size()) >= count) break;
+                const std::size_t n     = bucket->size();
+                const std::size_t start = std::uniform_int_distribution<std::size_t>(0, n - 1)(rng_);
+                for (std::size_t k = 0; k < n && int(result.size()) < count; ++k)
+                    try_new_piece((*bucket)[(start + k) % n]);
+            }
+            break;
+        }
+        case PickMode::RarestFirst:
+            // Visit buckets best-first: High priority before Normal, and within a
+            // priority ascending availability (rarest first). Within a bucket every
+            // piece is equally good, so start at a random offset and wrap around:
+            // this spreads concurrent peers across the rarest pieces instead of all
+            // converging on the same one — without any sorting here.
+            for (int pi = 0; pi < kNumPrio && int(result.size()) < count; ++pi) {
+                std::vector<std::vector<std::uint32_t>>& col = buckets_[pi];
+                for (std::uint32_t av = 0; av < col.size() && int(result.size()) < count; ++av) {
+                    std::vector<std::uint32_t>& bucket = col[av];
+                    if (bucket.empty()) continue;
+                    const std::size_t n     = bucket.size();
+                    const std::size_t start = std::uniform_int_distribution<std::size_t>(0, n - 1)(rng_);
+                    for (std::size_t k = 0; k < n && int(result.size()) < count; ++k)
+                        try_new_piece(bucket[(start + k) % n]);
+                }
+            }
+            break;
+    }
+    if (int(result.size()) >= count) return result;
+
+    // 3) End-game. Only enter it once *every* wanted piece is already in progress
+    // (downloading_ covers all remaining wanted pieces) — i.e. near completion —
+    // so we don't start duplicating requests early in the download (PP-1). Before
+    // that, a peer whose blocks are all taken simply gets nothing this round.
+    if (downloading_.size() < pieces_left_) return result;  // fresh pieces still remain
+
+    // Duplicate at most ONE already-requested block per call (not this peer's whole
+    // budget) so an in-progress block isn't fetched from many peers at once.
+    for (const auto& [piece, dp] : downloading_) {
+        if (!wanted(piece) || !peer_has(piece)) continue;
+        const std::uint32_t nblocks = blocks_in_piece(piece);
+        for (std::uint32_t b = 0; b < nblocks; ++b) {
+            const Block& blk = dp.blocks[b];
+            if (blk.state != BlockState::Requested) continue;
+            if (std::find(blk.peers.begin(), blk.peers.end(), peer) != blk.peers.end()) continue;
+            result.push_back(PieceBlock{piece, b});
+            if (!endgame_) LOG_DEBUG("bt.picker", "entering end-game (" << pieces_left_
+                                                  << " piece(s) left, all in progress)");
+            endgame_ = true;
+            return result;  // one busy block per pick
+        }
+    }
+    return result;
+}
+
+} // namespace librats::bittorrent

package/native-src/src/librats/bittorrent/piece_picker.h

@@ -0,0 +1,201 @@
+#pragma once
+
+/**
+ * @file piece_picker.h
+ * @brief Decides which blocks to request next — the download strategy core.
+ *
+ * The picker tracks, for every piece: how many connected peers have it
+ * (availability), our download priority for it, whether we already have it, and
+ * — for pieces in progress — the per-block state machine
+ * (None → Requested → Writing → Finished). pick_blocks() turns all of that into
+ * a concrete list of blocks to ask a given peer for, honouring:
+ *
+ *   1. partial pieces first  — finish what's already started;
+ *   2. the active strategy   — rarest-first (default), sequential or random;
+ *   3. end-game              — once every needed block is already in flight,
+ *                              re-request outstanding blocks from other peers.
+ *
+ * pick_blocks() is a pure query: it never mutates state. The caller commits its
+ * choices with mark_requested(), so the two-queue request pipeline (reserved vs
+ * in-flight) stays in the peer connection. Owned by one torrent on the network
+ * thread — not thread-safe by design.
+ */
+
+#include "librats/bittorrent/bitfield.h"
+
+#include <array>
+#include <cstdint>
+#include <random>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+namespace librats::bittorrent {
+
+enum class PiecePriority : std::uint8_t {
+    DontDownload = 0,  ///< excluded from picking
+    Normal       = 1,
+    High         = 2,
+};
+
+enum class PickMode : std::uint8_t {
+    RarestFirst,  ///< default — fewest-available pieces first
+    Sequential,   ///< lowest piece index first (streaming)
+    Random,
+};
+
+enum class BlockState : std::uint8_t {
+    None,       ///< not requested
+    Requested,  ///< asked a peer, awaiting data
+    Writing,    ///< received, being written to disk
+    Finished,   ///< on disk
+};
+
+/// A single 16 KiB block, identified by its piece and its index within it.
+struct PieceBlock {
+    std::uint32_t piece = 0;
+    std::uint32_t block = 0;
+    bool operator==(const PieceBlock& o) const noexcept { return piece == o.piece && block == o.block; }
+    bool operator!=(const PieceBlock& o) const noexcept { return !(*this == o); }
+};
+
+class PiecePicker {
+public:
+    PiecePicker(std::uint32_t num_pieces, std::uint32_t piece_length, std::int64_t total_size);
+
+    // ---- geometry ----
+    std::uint32_t num_pieces()       const noexcept { return num_pieces_; }
+    std::uint32_t piece_length()     const noexcept { return piece_length_; }
+    std::uint32_t piece_size(std::uint32_t piece)      const noexcept;
+    std::uint32_t blocks_in_piece(std::uint32_t piece) const noexcept;
+    std::uint32_t block_size(std::uint32_t piece, std::uint32_t block) const noexcept;
+
+    // ---- our progress ----
+    void          we_have(std::uint32_t piece);
+    void          we_have_all();
+    bool          have_piece(std::uint32_t piece) const noexcept { return have_.get(piece); }
+    std::uint32_t num_have() const noexcept { return num_have_; }
+    bool          is_finished() const noexcept { return pieces_left_ == 0; }
+    Bitfield      have_bitfield() const { return have_; }
+    void          set_have_bitfield(const Bitfield& have);
+
+    // ---- priorities ----
+    void          set_piece_priority(std::uint32_t piece, PiecePriority priority);
+    PiecePriority piece_priority(std::uint32_t piece) const noexcept { return priority_[piece]; }
+
+    // ---- strategy ----
+    void     set_mode(PickMode mode) noexcept { mode_ = mode; }
+    PickMode mode() const noexcept { return mode_; }
+
+    // ---- peer availability ----
+    void          peer_has_piece(std::uint32_t piece);
+    void          peer_lost_piece(std::uint32_t piece);
+    void          inc_availability(const Bitfield& peer_have);
+    void          dec_availability(const Bitfield& peer_have);
+    void          inc_availability_all();   ///< a seed joined
+    void          dec_availability_all();
+    /// Effective availability: per-peer count plus the number of connected seeds
+    /// (seeds are tracked as one counter — see inc_availability_all).
+    std::uint32_t availability(std::uint32_t piece) const noexcept { return availability_[piece] + seeds_; }
+
+    // ---- block state machine ----
+    /// Up to @p count blocks that @p peer (holding @p peer_have) can serve and we
+    /// still need. Pure query — commit with mark_requested().
+    std::vector<PieceBlock> pick_blocks(const Bitfield& peer_have, int count, const void* peer);
+
+    void mark_requested(const PieceBlock& b, const void* peer);
+    /// Mark a received block as being written to disk. Returns the *other* peers
+    /// that also had this block requested (end-game duplicates) so the caller can
+    /// send them CANCEL; the block's requester set is then cleared. Empty in the
+    /// common, non-end-game case where only the delivering peer had it.
+    std::vector<const void*> mark_writing(const PieceBlock& b, const void* peer);
+    /// Mark a block on disk. Returns true if this completed the piece (all blocks
+    /// finished → ready to hash).
+    bool mark_finished(const PieceBlock& b);
+    /// A request failed/was rejected: drop @p peer from the block, freeing it if no
+    /// other peer is still on it.
+    void abort_block(const PieceBlock& b, const void* peer);
+    /// A peer vanished: free every block it had outstanding.
+    void cancel_peer(const void* peer);
+    /// Hash check failed: throw away a piece's block progress so it is re-downloaded.
+    void restore_piece(std::uint32_t piece);
+
+    BlockState block_state(std::uint32_t piece, std::uint32_t block) const;
+    bool       is_interesting(const Bitfield& peer_have) const;
+    /// True if @p piece is one we still want (not have, not DontDownload). O(1).
+    /// A peer that has this piece is therefore interesting to us — this lets the
+    /// interest update on a single HAVE stay O(1) instead of rescanning the whole
+    /// bitfield through is_interesting().
+    bool       piece_interesting(std::uint32_t piece) const noexcept {
+        return piece < num_pieces_ && wanted(piece);
+    }
+    bool       in_endgame() const noexcept { return endgame_; }
+    std::size_t num_downloading() const noexcept { return downloading_.size(); }
+
+private:
+    struct Block {
+        BlockState                  state = BlockState::None;
+        std::vector<const void*>    peers;   ///< requesters (>1 only in end-game)
+    };
+    struct DownloadingPiece {
+        std::vector<Block> blocks;
+        std::uint16_t      num_requested = 0;
+        std::uint16_t      num_writing   = 0;
+        std::uint16_t      num_finished  = 0;
+    };
+
+    bool wanted(std::uint32_t piece) const noexcept {
+        return priority_[piece] != PiecePriority::DontDownload && !have_.get(piece);
+    }
+    DownloadingPiece& downloading_for(std::uint32_t piece);
+    void append_free_blocks(std::uint32_t piece, int count, const void* peer,
+                            std::vector<PieceBlock>& out) const;
+
+    // ---- incremental rarest-first index ----
+    // Every wanted & not-yet-have piece sits in a bucket addressed directly by
+    // (priority level, availability). A single availability or priority change is
+    // an O(1) bucket move (order_remove + order_insert) — no tree, no node
+    // allocation. pick_blocks() walks the buckets best-first (High priority first,
+    // then ascending availability = rarest). availability is bounded by the peer
+    // count (seeds live in seeds_, not here), so the inner dimension stays small.
+    static constexpr int kNumPrio = 2;  ///< High (idx 0, picked first) and Normal (idx 1)
+    static int prio_idx(PiecePriority p) noexcept {
+        return p == PiecePriority::High ? 0 : 1;  // DontDownload is never bucketed
+    }
+    void order_insert(std::uint32_t piece);   ///< add piece to its bucket (if wanted & absent)
+    void order_remove(std::uint32_t piece);   ///< pull piece out of its current bucket (if present)
+    void avail_add(std::uint32_t piece, int delta);  ///< change availability, keeping the index sorted
+
+    std::uint32_t num_pieces_;
+    std::uint32_t piece_length_;
+    std::int64_t  total_size_;
+
+    std::vector<std::uint32_t>  availability_;
+    std::vector<PiecePriority>  priority_;
+    Bitfield                    have_;
+    std::uint32_t               num_have_    = 0;
+    std::uint32_t               pieces_left_ = 0;   ///< wanted & not-yet-have
+    PickMode                    mode_        = PickMode::RarestFirst;
+    bool                        endgame_     = false;
+    // Sequential cursor: every piece with index < seq_cursor_ is already `have`,
+    // so a sequential pick can start here instead of rescanning the completed
+    // prefix from 0 on every refill. Maintained only in we_have() (advances
+    // monotonically, O(n) total over the whole download).
+    std::uint32_t               seq_cursor_  = 0;
+    // Number of connected seeds (peers that have everything). Tracked as one
+    // counter instead of +1 on every piece; folded into availability().
+    std::uint32_t               seeds_       = 0;
+
+    std::unordered_map<std::uint32_t, DownloadingPiece> downloading_;
+
+    // Incremental rarest-first index: buckets_[prio_idx][availability] -> pieces.
+    // The inner vector grows on demand as higher availabilities appear (bounded by
+    // the peer count). order_pos_[p] is p's slot within its bucket (for O(1)
+    // swap-removal); in_order_[p] records whether p is currently bucketed at all.
+    std::array<std::vector<std::vector<std::uint32_t>>, kNumPrio> buckets_;
+    std::vector<std::uint32_t> order_pos_;
+    std::vector<std::uint8_t>  in_order_;
+    mutable std::mt19937       rng_;
+};
+
+} // namespace librats::bittorrent

package/native-src/src/librats/bittorrent/reactor.cpp

@@ -0,0 +1,97 @@
+#include "librats/bittorrent/reactor.h"
+
+namespace librats::bittorrent {
+
+Reactor::Reactor() : poller_(IOPoller::create()) {
+    if (is_valid_socket(notifier_.fd())) poller_->add(notifier_.fd(), PollIn);
+}
+
+Reactor::~Reactor() {
+    stop();
+}
+
+void Reactor::start() {
+    if (running_.exchange(true)) return;
+    thread_ = std::thread([this] {
+        loop_thread_ = std::this_thread::get_id();
+        while (running_.load()) run_one(1000);
+    });
+}
+
+void Reactor::run() {
+    running_.store(true);
+    loop_thread_ = std::this_thread::get_id();
+    while (running_.load()) run_one(1000);
+}
+
+void Reactor::stop() {
+    if (!running_.exchange(false)) {
+        if (thread_.joinable()) thread_.join();
+        return;
+    }
+    notifier_.signal();  // break the poll wait so the loop sees running_ == false
+    if (thread_.joinable()) thread_.join();
+}
+
+void Reactor::post(Task task) {
+    tasks_.push(std::move(task));
+    notifier_.signal();
+}
+
+void Reactor::run_one(int timeout_ms) {
+    if (loop_thread_ == std::thread::id{}) loop_thread_ = std::this_thread::get_id();
+
+    const int wait_ms = timers_.next_timeout_ms(timeout_ms);
+    PollResult results[128];
+    const int n = poller_->wait(results, 128, wait_ms);
+
+    for (int i = 0; i < n; ++i) {
+        if (results[i].fd == notifier_.fd()) {
+            notifier_.drain();
+            continue;
+        }
+        auto it = handlers_.find(results[i].fd);
+        if (it == handlers_.end()) continue;
+        // Copy the callback: it may remove this very fd (and destroy the stored
+        // std::function) while running.
+        IoCallback cb = it->second;
+        cb(results[i].events);
+    }
+
+    run_tasks();
+    timers_.run_due();
+}
+
+void Reactor::run_tasks() {
+    tasks_.drain(task_scratch_);
+    for (auto& t : task_scratch_) t();
+    task_scratch_.clear();
+}
+
+bool Reactor::add(socket_t fd, std::uint32_t events, IoCallback cb) {
+    handlers_[fd] = std::move(cb);
+    if (!poller_->add(fd, events)) {
+        handlers_.erase(fd);
+        return false;
+    }
+    return true;
+}
+
+bool Reactor::modify(socket_t fd, std::uint32_t events) {
+    return poller_->modify(fd, events);
+}
+
+void Reactor::remove(socket_t fd) {
+    poller_->remove(fd);
+    handlers_.erase(fd);
+}
+
+TimerId Reactor::schedule(std::chrono::milliseconds delay, TimerCallback cb) {
+    return timers_.schedule(delay, std::move(cb));
+}
+
+void Reactor::cancel(TimerId id) {
+    timers_.cancel(id);
+}
+
+} // namespace librats::bittorrent