2 files changed, 27 insertions, 9 deletions

diff --git a/bittorrent/src/Network/BitTorrent/Exchange/Bitfield.hs b/bittorrent/src/Network/BitTorrent/Exchange/Bitfield.hs
index 7bae3475..1be9f970 100644
--- a/bittorrent/src/Network/BitTorrent/Exchange/Bitfield.hs
+++ b/bittorrent/src/Network/BitTorrent/Exchange/Bitfield.hs
@@ -9,7 +9,7 @@
 --   bitfields. Bitfields are used to keep track indices of complete
 --   pieces either this peer have or remote peer have.
 --
---   There are also commonly used piece seletion algorithms
+--   There are also commonly used piece selection algorithms
 --   which used to find out which one next piece to download.
 --   Selectors considered to be used in the following order:
 --
@@ -108,12 +108,17 @@ import Data.Torrent
 
 -- TODO cache some operations
 
--- | Bitfields are represented just as integer sets but with
--- restriction: the each set should be within given interval (or
--- subset of the specified interval). Size is used to specify
--- interval, so bitfield of size 10 might contain only indices in
--- interval [0..9].
+-- | Bitfields are represented just as integer sets but with a restriction:
+-- each integer in the set should be within the given interval.  The greatest
+-- lower bound of the interval must be zero, so intervals may be specified by
+-- providing a maximum set size.  For example, a bitfield of size 10 might
+-- contain only indices in interval [0..9].
 --
+-- By convention, we use the following aliases for Int:
+--
+--   [ PieceIx ] an Int member of the Bitfield.
+--
+--   [ PieceCount ] maximum set size for a Bitfield.
 data Bitfield = Bitfield {
     bfSize :: !PieceCount
   , bfSet  :: !IntSet
@@ -257,6 +262,7 @@ rarest xs
     = Just $ fst $ V.ifoldr' minIx (0, freqMap V.! 0) freqMap
   where
     freqMap = frequencies xs
+    {-# NOINLINE freqMap #-}
 
     minIx ::  PieceIx -> Frequency
           -> (PieceIx,   Frequency)
@@ -393,7 +399,7 @@ rarestFirst h a xs = rarest (map (intersection want) xs)
 randomFirst :: Selector
 randomFirst = do
 --  randomIO
-  error "randomFirst"
+  error "TODO: randomFirst"
 
 endGame :: Selector
 endGame = strictLast
diff --git a/bittorrent/src/System/Torrent/FileMap.hs b/bittorrent/src/System/Torrent/FileMap.hs
index 6e8d7f5a..38c475e8 100644
--- a/bittorrent/src/System/Torrent/FileMap.hs
+++ b/bittorrent/src/System/Torrent/FileMap.hs
@@ -39,7 +39,7 @@ import Data.Torrent
 
 data FileEntry = FileEntry
   { filePosition :: {-# UNPACK #-} !FileOffset
-  , fileBytes    :: {-# UNPACK #-} !BS.ByteString
+  , fileBytes    :: {-# UNPACK #-} !BS.ByteString -- XXX: mutable buffer (see 'writeBytes').
   } deriving (Show, Eq)
 
 type FileMap = Vector FileEntry
@@ -62,6 +62,7 @@ unmapFiles = V.mapM_ unmapEntry
   where
     unmapEntry (FileEntry _ (PS fptr _ _)) = finalizeForeignPtr fptr
 
+-- Unsafe: FileMap 'writeBytes' will modify supplied bytestrings in place.
 fromLazyByteString :: BL.ByteString -> FileMap
 fromLazyByteString lbs = V.unfoldr f (0, lbs)
   where
@@ -70,6 +71,8 @@ fromLazyByteString lbs = V.unfoldr f (0, lbs)
       where chunkSize = fromIntegral $ BS.length x
 
 -- | /O(n)/.
+--
+-- Unsafe: mutable buffers are returned without copy.
 toLazyByteString :: FileMap -> BL.ByteString
 toLazyByteString = V.foldr f Empty
   where
@@ -82,6 +85,7 @@ size m
   | FileEntry {..} <- V.unsafeLast m
   = filePosition + fromIntegral (BS.length fileBytes)
 
+-- | Find the file number for a particular byte offset within a torrent.
 bsearch :: FileOffset -> FileMap -> Maybe Int
 bsearch x m
   | V.null m  = Nothing
@@ -114,12 +118,17 @@ take len m
     s =  System.Torrent.FileMap.size m
 
 -- | /O(log n + m)/. Do not use this function with 'unmapFiles'.
+--
+-- The returned bytestring points directly into an area memory mapped from a
+-- file.
 unsafeReadBytes :: FileOffset -> FileSize -> FileMap -> BL.ByteString
 unsafeReadBytes off s m
   | (l  , m') <- System.Torrent.FileMap.drop off     m
   , (m'', _ ) <- System.Torrent.FileMap.take (off + s) m'
   = BL.take (fromIntegral s) $ BL.drop (fromIntegral l) $ toLazyByteString m''
 
+-- The returned bytestring is copied and safe to use after the file is
+-- unmapped.
 readBytes :: FileOffset -> FileSize -> FileMap -> IO BL.ByteString
 readBytes off s m = do
     let bs_copy = BL.copy $ unsafeReadBytes off s m
@@ -129,6 +138,8 @@ readBytes off s m = do
     forceLBS  Empty      = return ()
     forceLBS (Chunk _ x) = forceLBS x
 
+-- UNSAFE: Uses the first byte string as a pointer to mutable data and writes
+-- the contents of the second bytestring there.
 bscpy :: BL.ByteString -> BL.ByteString -> IO ()
 bscpy (PS _ _ 0 `Chunk` dest_rest) src                         = bscpy dest_rest src
 bscpy dest                         (PS _ _ 0 `Chunk` src_rest) = bscpy dest      src_rest
@@ -144,8 +155,9 @@ bscpy (PS dest_fptr dest_off dest_size `Chunk` dest_rest)
              (PS src_fptr  (src_off  + csize) (src_size  - csize) `Chunk` src_rest)
 bscpy _ _ = return ()
 
+-- UNSAFE: Mutates bytestring contents within the provided FileMap.
 writeBytes :: FileOffset -> BL.ByteString -> FileMap -> IO ()
 writeBytes off lbs m = bscpy dest src
   where
     src  = BL.take (fromIntegral (BL.length dest)) lbs
-    dest = unsafeReadBytes off (fromIntegral (BL.length lbs)) m
\ No newline at end of file
+    dest = unsafeReadBytes off (fromIntegral (BL.length lbs)) m