quartz_torrent 0.0.2 → 0.0.3

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Jeffrey A. Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,6 +1,8 @@
 QuartzTorrent -- A Ruby Bittorrent Library 
 ==========================================
 
+[![Gem Version](https://badge.fury.io/rb/quartz_torrent.png)](http://badge.fury.io/rb/quartz\_torrent)
+
 Like the title says, a bittorrent library implemented in pure ruby. Currently 
 the library works, but is still alpha.
 

data/lib/quartz_torrent/bitfield.rb

@@ -52,6 +52,17 @@ puts "]"
     # Length of the Bitfield in bits.
     attr_reader :length
 
+    # Adjust the length of the bitfield. This might be necessary if we had to unserialize the bitfield from
+    # a serialized array of bytes.
+    def length=(l)
+      byteLen = 0
+      byteLen = (l-1)/8+1 if l > 0
+
+      raise "Length adjustment would change size of underlying array" if byteLen != byteLength
+
+      @length = l
+    end
+
     
     # Length of the Bitfield in bytes.
     def byteLength

data/lib/quartz_torrent/extension.rb

@@ -1,13 +1,15 @@
 require 'quartz_torrent/peermsg'
 module QuartzTorrent
-  # This class contains constants that represent our numbering of the Bittorrent extensions we support.
+  # This class contains constants that represent our numbering of the Bittorrent peer-protocol extensions we support.
   # It also has some utility methods related to extensions.
   class Extension
   
+    # The metadata extension (BEP 9)
     MetadataExtensionId = 1
 
-    # Parameter info should be the metadata info struct. It is used to determine the size to send 
-    # when negotiating the metadata extension.
+    # Create an ExtendedHandshake object based on the passed Torrent metadata info struct. 
+    # @param info The torrent metadata info struct. It is used to determine the size to send 
+    #             when negotiating the metadata extension.
     def self.createExtendedHandshake(info)
       msg = ExtendedHandshake.new
       
@@ -26,6 +28,8 @@ module QuartzTorrent
       msg
     end
 
+    # Get the class to use to serialize and unserialize the specified Bittorent extension. Returns nil if we don't support that extension.
+    # @param info The name of a bittorrent extension as specified in the BEP, for example 'ut_metadata'.
     def self.peerMsgClassForExtensionName(info)
       if info == 'ut_metadata'
         ExtendedMetaInfo

data/lib/quartz_torrent/formatter.rb

@@ -2,8 +2,11 @@ module QuartzTorrent
   # Class that can be used to format different quantities into 
   # human readable strings.
   class Formatter
+    # Number of bytes in a Kilobyte.
     Kb = 1024
+    # Number of bytes in a Megabyte.
     Meg = 1024*Kb
+    # Number of bytes in a Gigabyte.
     Gig = 1024*Meg
 
     # Format a size in bytes.

data/lib/quartz_torrent/magnet.rb

@@ -20,6 +20,7 @@ module QuartzTorrent
 
     attr_reader :raw
 
+    # Returns true if the passed string is a magnet URI, false otherwise.
     def self.magnetURI?(str)
       str =~ @@regex
     end

data/lib/quartz_torrent/metainfopiecestate.rb

@@ -118,6 +118,7 @@ module QuartzTorrent
       num*BlockSize + extra
     end
 
+    # Return true if the specified piece is completed. The piece is specified by index.
     def pieceCompleted?(pieceIndex)
       @completePieces.set? pieceIndex
     end
@@ -132,12 +133,15 @@ module QuartzTorrent
       raise "Metadata is not yet complete" if ! complete?
     end
 
+    # Save the specified piece to disk asynchronously.
     def savePiece(pieceIndex, data)
       id = @pieceManager.writeBlock pieceIndex, 0, data
       @pieceManagerRequests[id] = PieceManagerRequestMetadata.new(:write, pieceIndex)
       id
     end
 
+    # Read a piece from disk. This method is asynchronous; it returns a handle that can be later
+    # used to retreive the result.
     def readPiece(pieceIndex)
       length = BlockSize
       length = @lastPieceLength if pieceIndex == @numPieces - 1
@@ -180,6 +184,7 @@ module QuartzTorrent
       results
     end
 
+    # Return a list of torrent pieces that can still be requested. These are pieces that are not completed and are not requested.
     def findRequestablePieces
       piecesRequired = []
 
@@ -192,6 +197,8 @@ module QuartzTorrent
       piecesRequired
     end
 
+    # Return a list of peers from whom we can request pieces. These are peers for whom we have an established connection, and 
+    # are not marked as bad. See markPeerBad.
     def findRequestablePeers(classifiedPeers)
       result = []
 
@@ -213,6 +220,8 @@ module QuartzTorrent
       end
     end
 
+    # Mark the specified peer as 'bad'. We won't try requesting pieces from this peer. Used, for example, when
+    # a peer rejects our request for a metadata piece. 
     def markPeerBad(peer)
       @badPeers.add peer
     end
@@ -229,6 +238,7 @@ module QuartzTorrent
       @pieceManager.wait
     end
 
+    # Return the name of the file where this class will store the Torrent Info struct.
     def self.generateInfoFileName(infoHash)
       "#{QuartzTorrent.bytesToHex(infoHash)}.info"
     end

data/lib/quartz_torrent/peer.rb

@@ -2,9 +2,11 @@ require 'quartz_torrent/rate'
 require 'quartz_torrent/peermsgserialization'
 
 module QuartzTorrent
+  # This class represents a torrent peer. 
   class Peer
     @@stateChangeListeners = []
 
+    # Create a new Peer using the information from the passed TrackerPeer object.
     def initialize(trackerPeer)
       @trackerPeer = trackerPeer
       @amChoked = true
@@ -86,6 +88,7 @@ module QuartzTorrent
     # A PeerWireMessageSerializer that can unserialize and serialize messages to and from this peer.
     attr_accessor :peerMsgSerializer
 
+    # Return a string representation of the peer.
     def to_s
       @trackerPeer.to_s
     end
@@ -95,6 +98,7 @@ module QuartzTorrent
       @@stateChangeListeners.push l
     end
 
+    # Equate peers.
     def eql?(o)
       o.is_a?(Peer) && trackerPeer.eql?(o.trackerPeer)
     end

data/lib/quartz_torrent/peerclient.rb

@@ -4,7 +4,6 @@ require "quartz_torrent/peermsg.rb"
 require "quartz_torrent/reactor.rb"
 require "quartz_torrent/util.rb"
 require "quartz_torrent/classifiedpeers.rb"
-require "quartz_torrent/classifiedpeers.rb"
 require "quartz_torrent/peerholder.rb"
 require "quartz_torrent/peermanager.rb"
 require "quartz_torrent/blockstate.rb"
@@ -38,6 +37,8 @@ module QuartzTorrent
       @peerManager = PeerManager.new
       @pieceManagerRequestMetadata = {}
       @pieceManagerMetainfoRequestMetadata = {}
+      @bytesDownloadedDataOnly = 0
+      @bytesUploadedDataOnly = 0
       @bytesDownloaded = 0
       @bytesUploaded = 0
       @magnet = nil
@@ -72,6 +73,8 @@ module QuartzTorrent
     # Metadata associated with outstanding requests to the PieceManager responsible for the pieces of the torrent metainfo.
     attr_accessor :pieceManagerMetainfoRequestMetadata
     attr_accessor :peerChangeListener
+    attr_accessor :bytesDownloadedDataOnly
+    attr_accessor :bytesUploadedDataOnly
     attr_accessor :bytesDownloaded
     attr_accessor :bytesUploaded
     attr_accessor :state
@@ -143,6 +146,10 @@ module QuartzTorrent
     # After we have completed downloading a torrent, we will continue to upload until we have 
     # uploaded ratio * torrent_size bytes. If nil, no limit on upload.
     attr_accessor :ratio
+    attr_accessor :bytesUploadedDataOnly
+    attr_accessor :bytesDownloadedDataOnly
+    attr_accessor :bytesUploaded
+    attr_accessor :bytesDownloaded
   
     # Update the data in this TorrentDataDelegate from the torrentData
     # object that it was created from. TODO: What if that torrentData is now gone?
@@ -160,6 +167,8 @@ module QuartzTorrent
     def fillFrom(torrentData)
       @infoHash = torrentData.infoHash
       @info = torrentData.info
+      @bytesUploadedDataOnly = torrentData.bytesUploadedDataOnly
+      @bytesDownloadedDataOnly = torrentData.bytesDownloadedDataOnly
       @bytesUploaded = torrentData.bytesUploaded
       @bytesDownloaded = torrentData.bytesDownloaded
 
@@ -296,7 +305,7 @@ module QuartzTorrent
         @logger.warn "Asked to set download rate limit for a non-existent torrent #{QuartzTorrent.bytesToHex(infoHash)}"
         return
       end
-      
+ 
       if bytesPerSecond
         if ! torrentData.downRateLimit
           torrentData.downRateLimit = RateLimit.new(bytesPerSecond, 2*bytesPerSecond, 0)
@@ -306,6 +315,13 @@ module QuartzTorrent
       else
         torrentData.downRateLimit = nil
       end
+
+      torrentData.peers.all.each do |peer|
+        withPeersIo(peer, "setting download rate limit") do |io|
+          io.readRateLimit = torrentData.downRateLimit
+        end
+      end
+     
     end
 
     # Set the upload rate limit. Pass nil as the bytesPerSecond to disable the limit.
@@ -325,6 +341,12 @@ module QuartzTorrent
       else
         torrentData.upRateLimit = nil
       end
+
+      torrentData.peers.all.each do |peer|
+        withPeersIo(peer, "setting upload rate limit") do |io|
+          io.writeRateLimit = torrentData.upRateLimit
+        end
+      end
     end
 
     # Set the upload ratio. Pass nil to disable
@@ -503,7 +525,10 @@ module QuartzTorrent
           close
           return
         end
+
         peer.updateUploadRate msg
+        torrentData = @torrentData[peer.infoHash]
+        torrentData.bytesDownloaded += msg.length if torrentData
         @logger.debug "Peer #{peer} upload rate: #{peer.uploadRate.value}  data only: #{peer.uploadRateDataOnly.value}"
       end
 
@@ -801,7 +826,7 @@ module QuartzTorrent
       end
 
       if torrentData.state == :uploading && (torrentData.state != :paused) && torrentData.ratio
-        if torrentData.bytesUploaded >= torrentData.ratio*torrentData.blockState.totalLength
+        if torrentData.bytesUploadedDataOnly >= torrentData.ratio*torrentData.blockState.totalLength
           @logger.info "Pausing torrent due to upload ratio limit." if torrentData.metainfoPieceState.complete?
           setPaused(infoHash, true)
           return
@@ -978,7 +1003,7 @@ module QuartzTorrent
       peer.requestedBlocks.delete blockInfo.blockIndex
       # Block is marked as not requested when hash is confirmed
 
-      torrentData.bytesDownloaded += msg.data.length
+      torrentData.bytesDownloadedDataOnly += msg.data.length
       id = torrentData.pieceManager.writeBlock(msg.pieceIndex, msg.blockOffset, msg.data)
       torrentData.pieceManagerRequestMetadata[id] = PieceManagerRequestMetadata.new(:write, msg)
     end
@@ -1011,6 +1036,7 @@ module QuartzTorrent
       end
 
       peer.bitfield = msg.bitfield
+      peer.bitfield.length = torrentData.info.pieces.length
 
       if ! torrentData.blockState
         @logger.warn "Bitfield: no blockstate yet."
@@ -1100,8 +1126,9 @@ module QuartzTorrent
               msg.pieceIndex = readRequestMetadata.requestMsg.pieceIndex
               msg.blockOffset = readRequestMetadata.requestMsg.blockOffset
               msg.data = result.data
+              @logger.debug "Sending block to #{peer}: piece #{msg.pieceIndex} offset #{msg.blockOffset} length #{msg.data.length}"
               sendMessageToPeer msg, io, peer
-              torrentData.bytesUploaded += msg.data.length
+              torrentData.bytesUploadedDataOnly += msg.data.length
               @logger.debug "Sending piece to peer"
             end
           else
@@ -1313,12 +1340,14 @@ module QuartzTorrent
 
     def sendMessageToPeer(msg, io, peer)
       peer.updateDownloadRate(msg)
+      torrentData = @torrentData[peer.infoHash]
+      torrentData.bytesUploaded += msg.length if torrentData
+
       begin
         peer.peerMsgSerializer.serializeTo(msg, io)
       rescue
         @logger.warn "Sending message to peer #{peer} failed: #{$!.message}"
       end
-      msg.serializeTo io
     end
 
     # Update our internal peer list for this torrent from the tracker client
@@ -1602,8 +1631,8 @@ module QuartzTorrent
         result = TrackerDynamicRequestParams.new(dataLength)
         if torrentData && torrentData.blockState
           result.left = torrentData.blockState.totalLength - torrentData.blockState.completedLength
-          result.downloaded = torrentData.bytesDownloaded
-          result.uploaded = torrentData.bytesUploaded
+          result.downloaded = torrentData.bytesDownloadedDataOnly
+          result.uploaded = torrentData.bytesUploadedDataOnly
         end
         result
       end

data/lib/quartz_torrent/peerholder.rb

@@ -2,6 +2,7 @@ require 'quartz_torrent/peer.rb'
 require 'quartz_torrent/util'
 
 module QuartzTorrent
+  # A container class for holding torrent peers. Allows lookup by different properties.
   class PeerHolder
     def initialize
       @peersById = {}
@@ -10,20 +11,24 @@ module QuartzTorrent
       @log = LogManager.getLogger("peerholder")
     end
 
+    # Find a peer by its trackerpeer's peerid. This is the id returned by the tracker, and may be nil.
     def findById(peerId)
       @peersById[peerId]
     end
 
+    # Find a peer by its IP address and port.
     def findByAddr(ip, port)
       @peersByAddr[ip + port.to_s]
     end
 
+    # Find all peers related to the torrent with the passed infoHash.
     def findByInfoHash(infoHash)
       l = @peersByInfoHash[infoHash]
       l = [] if ! l
       l
     end
 
+    # Add a peer to the PeerHolder.
     def add(peer)
       raise "Peer must have it's infoHash set." if ! peer.infoHash
 
@@ -44,7 +49,7 @@ module QuartzTorrent
       @peersByInfoHash.pushToList(peer.infoHash, peer)
     end
 
-    # This peer, which previously had no id, has finished handshaking and now has an ID.
+    # Set the id for a peer. This peer, which previously had no id, has finished handshaking and now has an ID.
     def idSet(peer)
       @peersById.each do |e| 
         return if e.eql?(peer)
@@ -52,6 +57,7 @@ module QuartzTorrent
       @peersById.pushToList(peer.trackerPeer.id, peer)
     end
 
+    # Delete the specified peer from the PeerHolder.
     def delete(peer)
       @peersByAddr.delete byAddrKey(peer)
 
@@ -82,14 +88,17 @@ module QuartzTorrent
       end
     end
 
+    # Return the list of all peers.
     def all
       @peersByAddr.values
     end
 
+    # Return the number of peers in the holder.
     def size
       @peersByAddr.size
     end
 
+    # Output a string representation of the PeerHolder, for debugging purposes.
     def to_s(infoHash = nil)
       def makeFlags(peer)
         s = "["

data/lib/quartz_torrent/peermsg.rb

@@ -87,12 +87,15 @@ module QuartzTorrent
     MessageCancel = 8
     MessageExtended = 20
 
+    # Create a new PeerWireMessage with the specified message id.
     def initialize(messageId)
       @messageId = messageId
     end
 
+    # Get the message id of this message (the message type from the peer wire protocol). 
     attr_reader :messageId
 
+    # Serialize this message to the passed io
     def serializeTo(io)
       io.write [payloadLength+1].pack("N")
       io.write [@messageId].pack("C")
@@ -108,6 +111,7 @@ module QuartzTorrent
       payloadLength + 5
     end
 
+    # Unserialize the message from the passed string.
     def unserialize(payload)
       raise "Subclasses of PeerWireMessage must implement unserialize but #{self.class} didn't"
     end

data/lib/quartz_torrent/reactor.rb

@@ -21,7 +21,7 @@ module QuartzTorrent
     def serverInit(metainfo, addr, port)
     end
 
-    # Event handler. The current io is ready for reading
+    # Event handler: The current io is ready for reading.
     # If you will write to the same io from both this handler and the timerExpired handler,
     # you must make sure to perform all writing at once in this handler. If not then 
     # the writes from the timer handler may be interleaved. 
@@ -43,19 +43,22 @@ module QuartzTorrent
     def recvData(metainfo)
     end
 
-    # Event handler. A timer has expired
+    # Event handler: a timer has expired. 
+    # @param metainfo The metainfo associated with the timer, that was passed to scheduleTimer.
     def timerExpired(metainfo)
     end
 
-    # Event handler. Error during read, or write. Connection errors are reported separately in connectError
+    # Event handler: an error occurred during read or write. Connection errors are reported separately in connectError
+    # @param metainfo The metainfo associated with the io.
     def error(metainfo, details)
     end
 
-    # Event handler. Error during connection, or connection timed out.
+    # Event handler: an error occurred during connection, or connection timed out.
+    # @param metainfo The metainfo associated with the io, as passed to the connect method.
     def connectError(metainfo, details)
     end
 
-    # Event handler. This is called for events added using addUserEvent to the reactor.
+    # Event handler: this is called for events added using addUserEvent to the reactor.
     def userEvent(event)
     end
 
@@ -63,6 +66,12 @@ module QuartzTorrent
     attr_accessor :reactor
 
     # Schedule a timer.
+    # @param duration  The duration of the timer in seconds
+    # @param metainfo  The metainfo to associate with the timer
+    # @param recurring If true when the timer duration expires, the timer will be rescheduled. If false the timer 
+    #                     will not be rescheduled.
+    # @param immed     If true then the timer will expire immediately (the next pass through the event loop). If the timer
+    #                     is also recurring it will then be rescheduled according to it's duratoin.
     def scheduleTimer(duration, metainfo = nil, recurring = true, immed = false)
       @reactor.scheduleTimer(duration, metainfo, recurring, immed) if @reactor
     end  
@@ -73,48 +82,52 @@ module QuartzTorrent
       @reactor.cancelTimer(timerInfo) if @reactor
     end
 
+    # Create a TCP connection to the specified host and port. Associate the passed metainfo with the IO representing the connection.
     def connect(addr, port, metainfo, timeout = nil)
       @reactor.connect(addr, port, metainfo, timeout) if @reactor
     end
 
-    # Write data to the current io
+    # Write data to the current io.
     def write(data)
       @reactor.write(data) if @reactor
     end
 
-    # Read len bytes from the current io
+    # Read len bytes from the current io. This is meant to be called from one of the event handler methods.
     def read(len)
       result = ''
       result = @reactor.read(len) if @reactor 
       result
     end
 
-    # Shutdown the reactor
+    # Shutdown the reactor.
     def stopReactor
       @reactor.stop if @reactor
     end
   
-    # Check if stop has been called on the reactor 
+    # Check if stop has been called on the reactor.
     def stopped?
       @stopped
     end
 
-    # Close the current io
+    # Close the current io. This is meant to be called from one of the event handler methods.
     def close(io = nil)
       @reactor.close(io) if @reactor
     end
 
+    # Return the current IO object. This is meant to be called from one of the event handler methods. 
+    # The returned object is actually an IoFacade, a wrapper around the IO object.
     def currentIo
       result = nil
       result = @reactor.currentIo if @reactor
       result
     end
     
-    # Find an io by metainfo
+    # Find an io by metainfo.
     def findIoByMetainfo(metainfo)
       @reactor.findIoByMetainfo metainfo if metainfo && @reactor
     end
-
+  
+    # Set the metainfo for the current io. This is meant to be called from one of the event handler methods.
     def setMetaInfo(metainfo)
       @reactor.setMetaInfo metainfo if @reactor
     end
@@ -130,6 +143,8 @@ module QuartzTorrent
     end
   end
   
+  # Simple class used to buffer output for an IO until it's ready for writing. This is not part of the 
+  # public API; it's used internally by the IOInfo class.
   class OutputBuffer
     # Create a new OutputBuffer for the specified IO. The parameter seekable should be
     # true or false. If true, then this output buffer will support seek
@@ -144,14 +159,17 @@ module QuartzTorrent
       end
     end
 
+    # Is the buffer empty?
     def empty?
       @buffer.length == 0
     end
 
+    # Number of bytes in the buffer.
     def size
       @buffer.length
     end
 
+    # Append data to the buffer.
     def append(data)
       if ! @seekable
         @buffer << data
@@ -208,6 +226,7 @@ module QuartzTorrent
       hash.delete @io
     end
 
+    # Read `length` bytes.
     def read(length)
       data = ''
       while data.length < length
@@ -249,6 +268,7 @@ module QuartzTorrent
       data
     end
 
+    # Write data to the IO.
     def write(data)
       # Issue: what about write, read, read on files opened for read/write? Write should happen at offset X, but reads moved to offset N. Since writes
       # are buffered, write may happen after read which means write will happen at the wrong offset N. Can fix by always seeking (if needed) before writes to the 
@@ -259,37 +279,61 @@ module QuartzTorrent
       data.length
     end
 
+    # Seek on the io. 
+    # @param amount  amount to seek.
+    # @param whence  one of the whence constants from IO::seek.
     def seek(amount, whence)
       @io.seek amount, whence if @ioInfo.seekable?
     end
 
+    # Flush data.
     def flush
       @io.flush
     end
   
+    # Close the io.
     def close
       @io.close
     end
 
+    # Check if the io is closed.
     def closed?
       @io.closed?
     end
+
+    def readRateLimit=(rate)
+      raise "The argument must be a RateLimit" if ! rate.nil? && ! rate.is_a?(RateLimit)
+      @ioInfo.readRateLimit = rate
+    end
+
+    def writeRateLimit=(rate)
+      raise "The argument must be a RateLimit" if ! rate.nil? && !rate.is_a?(RateLimit)
+      @ioInfo.writeRateLimit = rate
+    end
+
+    attr_accessor :writeRateLimit
   end
 
-  # An IoFacade that doesn't allow reading.
+  # An IoFacade that doesn't allow reading. This is not part of the public API.
   class WriteOnlyIoFacade < IoFacade
+    # Create a new WriteOnlyIoFacade that delegates to the passed IOInfo object.
     def initialize(ioInfo, logger = nil, readError = "Reading is not allowed for this IO")
       super(ioInfo, logger)
       @readError = readError
     end
 
+    # Raise an exception.
     def read(length)
       raise @readError
     end
   end
 
-  # An IO and associated meta-information used by the Reactor.
+  # An IO and associated meta-information used by the Reactor. This is not part of the public API.
   class IOInfo
+    # Create a new IOInfo object that operates on the passed IO object.
+    # @param io       An IO object
+    # @param metainfo The metainfo to associate with the IO.
+    # @param seekable Whether the IO is seekable or not.
     def initialize(io, metainfo, seekable = false)
       @io = io
       @metainfo = metainfo
@@ -315,6 +359,8 @@ module QuartzTorrent
     attr_accessor :useErrorhandler
     attr_accessor :readRateLimit
     attr_accessor :writeRateLimit
+
+    # Is the IO seekable.
     def seekable?
       @seekable
     end
@@ -583,13 +629,15 @@ module QuartzTorrent
     end
 
     # Meant to be called from the handler. Sets the max rate at which the current io can read.
-    def setReadRateLimit(rateLimit)
-      @currentIoInfo.readRateLimit = rateLimit
+    def setReadRateLimit(rate)
+      raise "The argument must be a RateLimit" if ! rate.nil? && !rate.is_a?(RateLimit)
+      @currentIoInfo.readRateLimit = rate
     end
 
     # Meant to be called from the handler. Sets the max rate at which the current io can be written to.
-    def setWriteRateLimit(rateLimit)
-      @currentIoInfo.writeRateLimit = rateLimit
+    def setWriteRateLimit(rate)
+      raise "The argument must be a RateLimit" if ! rate.nil? && !rate.is_a?(RateLimit)
+      @currentIoInfo.writeRateLimit = rate
     end
 
     # Meant to be called from the handler. Find an IO by metainfo. The == operator is used to 
@@ -653,18 +701,6 @@ module QuartzTorrent
         rescue
           # Exception occurred. Probably EINTR.
           @logger.warn "Select raised exception; will retry. Reason: #{$!}" if @logger
-@logger.warn "IOs at time of failure:"
-@logger.warn "Readset:"
-readset.each do |io|
-  ioInfo = @ioInfo[io]
-  puts "  #{ioInfo.metainfo}: #{(io.closed?) ? "closed" : "not closed"}"
-end
-@logger.warn "Writeset:"
-writeset.each do |io|
-  ioInfo = @ioInfo[io]
-  puts "  #{ioInfo.metainfo}: #{(io.closed?) ? "closed" : "not closed"}"
-end
-
         end
       end
 

data/lib/quartz_torrent/regionmap.rb

@@ -1,4 +1,6 @@
 class Array
+  # Perform a binary search for a value in the array between the index low and high. This method expects a block. The
+  # block is passed a value v, and should return true if the target value is >= v, and false otherwise.
   def binsearch(low = nil, high = nil) 
     return nil if length == 0
     result = binsearch_index(low, high){ |x| yield x if !x.nil?}
@@ -6,6 +8,8 @@ class Array
     result
   end
 
+  # Perform a binary search for an index in the array between the index low and high. This method expects a block. The
+  # block is passed a value v, and should return true if the target value is >= v, and false otherwise.
   def binsearch_index(low = nil, high = nil) 
     return nil if length == 0
     low = 0 if !low

data/lib/quartz_torrent/trackerclient.rb

@@ -35,17 +35,21 @@ module QuartzTorrent
       end
     end
 
+    # Hash code of this TrackerPeer.
     def hash
       @hash
     end
 
+    # Equate to another TrackerPeer.
     def eql?(o)
       o.ip == @ip && o.port == @port
     end
 
-    # Ip address, a string in dotted-quad notation
+    # IP address, a string in dotted-quad notation
     attr_accessor :ip
+    # TCP port
     attr_accessor :port
+    # Peer Id. This may be nil.
     attr_accessor :id
 
     def to_s
@@ -64,8 +68,11 @@ module QuartzTorrent
         @left = 0
       end
     end
+    # Number of bytes uploaded
     attr_accessor :uploaded
+    # Number of bytes downloaded
     attr_accessor :downloaded
+    # Number of bytes left to download before torrent is completed
     attr_accessor :left
   end
 
@@ -98,6 +105,9 @@ module QuartzTorrent
   class TrackerClient
     include QuartzTorrent
 
+    # Create a new TrackerClient
+    # @param announceUrl The announce URL of the tracker
+    # @param infoHash    The infoHash of the torrent we're tracking
     def initialize(announceUrl, infoHash, dataLength = 0, maxErrors = 20)
       @peerId = "-QR0001-" # Azureus style
       @peerId << Process.pid.to_s
@@ -126,10 +136,13 @@ module QuartzTorrent
     # with up-to-date information.
     attr_accessor :dynamicRequestParamsBuilder
 
+    # Return true if this TrackerClient is started, false otherwise.
     def started?
       @started
     end
 
+    # Return the list of peers that the TrackerClient knows about. This list grows over time
+    # as more peers are reported from the tracker.
     def peers
       result = nil
       @peersMutex.synchronize do
@@ -153,7 +166,8 @@ module QuartzTorrent
       @errors
     end
 
-    # Create a new TrackerClient using the passed information.
+    # Create a new TrackerClient using the passed information. This is a factory method that will return
+    # a tracker that talks the protocol specified in the URL.
     def self.create(announceUrl, infoHash, dataLength = 0, start = true)
       result = nil
       if announceUrl =~ /udp:\/\//
@@ -166,6 +180,7 @@ module QuartzTorrent
       result
     end
 
+    # Create a new TrackerClient using the passed Metainfo object.
     def self.createFromMetainfo(metainfo, start = true)
       create(metainfo.announce, metainfo.infoHash, metainfo.info.dataLength, start)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quartz_torrent
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -164,6 +164,7 @@ files:
 - lib/quartz_torrent/magnet.rb
 - lib/quartz_torrent/udptrackerclient.rb
 - README.md
+- LICENSE
 - .yardopts
 - bin/quartztorrent_download
 - bin/quartztorrent_download_curses