java.lang.Object
org.klomp.snark.Piece
All Implemented Interfaces:
Comparable<Piece>
class Pieceextends Object implements Comparable<Piece>
Represents a torrent piece and tracks which peers have it and are requesting it.

This class is used internally by PeerCoordinator to manage piece selection and distribution strategies. It maintains:

  • The piece identifier within the torrent
  • Set of peers that have this piece available
  • Set of peers currently requesting this piece
  • Priority level for piece selection

Pieces are sorted by priority (highest first) and then by rarity (fewest peers having it first) to optimize download performance.

Thread Safety: This class is not thread-safe. Callers must synchronize on access to most methods.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) long
    _lastActive
    Time of the last request or received chunk, for stall detection.
    private final int
    id
    Piece number within the torrent.
    private final Set<PeerID>
    peers
    Peers this piece was requested from.
    private int
    priority
    Download priority for this piece.
    private Set<PeerID>
    requests
    Peers currently requested from for this piece.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Piece(int id)
    Creates a new Piece with the given ID.

  • Method Summary

    Public Methods
    Modifier and Type
    Method
    Description
    boolean
    addPeer(Peer peer)
    Adds a peer to the set of peers that have this piece.
    void
    clear()
    Clear all knowledge of peers Caller must synchronize.
    int
    compareTo(Piece op)
    Compares by highest priority first, then by rarest first.
    boolean
    equals(Object o)
     
    int
    getId()
    Returns the piece index within the torrent.
    long
    getLastActive()
    Returns the time of the last request or received chunk for this piece.
    int
    getPeerCount()
    How many peers have this piece? Caller must synchronize.
    int
    getPriority()
    The current priority level for this piece.
    int
    getRequestCount()
    How many peers are requesting this piece? Caller must synchronize.
    Set<PeerID>
    getRequesters()
    Returns a snapshot of the peers currently requesting this piece.
    int
    hashCode()
     
    boolean
    isDisabled()
    Checks if this piece is disabled (should not be downloaded).
    boolean
    isRequested()
    Checks if any peer is currently requesting this piece.
    boolean
    isRequestedBy(Peer peer)
    Checks if the given peer is currently requesting this piece.
    boolean
    removePeer(Peer peer)
    Removes a peer from those that have this piece.
    void
    setActive()
    Records that this piece has just received a chunk, for stall detection.
    void
    setDisabled()
    Disables this piece so it will not be downloaded.
    void
    setPriority(int p)
    The priority level for this piece.
    (package private) void
    setRequested(PeerID pid, boolean requested)
    Marks a peer as requesting or no longer requesting this piece, stamping the last-activity time when a request is made.
    void
    setRequested(Peer peer, boolean requested)
    Marks a peer as requesting or no longer requesting this piece.
    String
    toString()
     

    Methods inherited from class Object

    clone, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • id

      private final int id
      Piece number within the torrent.

    • peers

      private final Set<PeerID> peers
      Peers this piece was requested from.

    • requests

      private volatile Set<PeerID> requests
      Peers currently requested from for this piece.

    • priority

      private int priority
      Download priority for this piece.

    • _lastActive

      volatile long _lastActive
      Time of the last request or received chunk, for stall detection.

  • Constructor Details

    • Piece

      public Piece(int id)
      Creates a new Piece with the given ID.
      Parameters:
      id - the piece index within the torrent

  • Method Details

    • compareTo

      public int compareTo(Piece op)
      Compares by highest priority first, then by rarest first.
      Specified by:
      compareTo in interface Comparable<Piece>
      Parameters:
      op - the other Piece to compare to
      Returns:
      negative if this piece has higher priority, positive if lower

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • getId

      public int getId()
      Returns the piece index within the torrent.
      Returns:
      the piece ID

    • addPeer

      public boolean addPeer(Peer peer)
      Adds a peer to the set of peers that have this piece. Caller must synchronize.
      Parameters:
      peer - the peer to credit with holding this piece, stored by peer ID
      Returns:
      true if the peer was added, false if already present

    • removePeer

      public boolean removePeer(Peer peer)
      Removes a peer from those that have this piece. Caller must synchronize.
      Parameters:
      peer - the peer to drop, matched against the stored peer ID
      Returns:
      true if removed

    • getPeerCount

      public int getPeerCount()
      How many peers have this piece? Caller must synchronize.
      Returns:
      number of peers that have this piece

    • isRequested

      public boolean isRequested()
      Checks if any peer is currently requesting this piece. Caller must synchronize.
      Returns:
      true if at least one peer is requesting this piece

    • setRequested

      public void setRequested(Peer peer, boolean requested)
      Marks a peer as requesting or no longer requesting this piece. Used to avoid deadlocks when querying each peer. Caller must synchronize.
      Parameters:
      peer - the peer whose request state is being set, stored by peer ID
      requested - true to mark as requested, false to unmark

    • setRequested

      void setRequested(PeerID pid, boolean requested)
      Marks a peer as requesting or no longer requesting this piece, stamping the last-activity time when a request is made. Used to avoid deadlocks when querying each peer. Caller must synchronize.
      Parameters:
      pid - the peer ID
      requested - true to mark as requested, false to unmark

    • setActive

      public void setActive()
      Records that this piece has just received a chunk, for stall detection.

    • getLastActive

      public long getLastActive()
      Returns the time of the last request or received chunk for this piece.
      Returns:
      the time in milliseconds

    • getRequesters

      public Set<PeerID> getRequesters()
      Returns a snapshot of the peers currently requesting this piece. Caller must synchronize.
      Returns:
      the requesting peers, or an empty set

    • isRequestedBy

      public boolean isRequestedBy(Peer peer)
      Checks if the given peer is currently requesting this piece. Caller must synchronize.
      Parameters:
      peer - the peer to test for, matched against the stored peer ID
      Returns:
      true if peer is requesting, false otherwise

    • getRequestCount

      public int getRequestCount()
      How many peers are requesting this piece? Caller must synchronize.
      Returns:
      number of peers requesting this piece

    • clear

      public void clear()
      Clear all knowledge of peers Caller must synchronize.

    • getPriority

      public int getPriority()
      The current priority level for this piece.
      Returns:
      priority value (negative values indicate disabled/skipped pieces)

    • setPriority

      public void setPriority(int p)
      The priority level for this piece.
      Parameters:
      p - priority value (negative to disable, 0 or positive for normal priority)

    • isDisabled

      public boolean isDisabled()
      Checks if this piece is disabled (should not be downloaded).
      Returns:
      true if disabled (priority < 0), false otherwise

    • setDisabled

      public void setDisabled()
      Disables this piece so it will not be downloaded. Sets priority to -1.

    • toString

      public String toString()
      Overrides:
      toString in class Object