Commented some unused bittorrent related code.

1 files changed, 14 insertions, 2 deletions

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