From 341b8c5715ca7d54523a70350dd21559aa9e9881 Mon Sep 17 00:00:00 2001
From: Brian Warner <warner@lothar.com>
Date: Sat, 7 Jan 2012 13:52:39 -0800
Subject: [PATCH] mutable: add comments about the tricky DeferredList
 structures in retrieve

---
 src/allmydata/mutable/filenode.py  | 4 +++-
 src/allmydata/mutable/servermap.py | 5 ++++-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/allmydata/mutable/filenode.py b/src/allmydata/mutable/filenode.py
index 08de545c..74ed7f0a 100644
--- a/src/allmydata/mutable/filenode.py
+++ b/src/allmydata/mutable/filenode.py
@@ -1143,6 +1143,7 @@ class MutableFileVersion:
         blockhashes = {} # shnum -> blockhash tree
         for (shnum, original_data) in update_data.iteritems():
             data = [d[1] for d in original_data if d[0] == self._version]
+            # data is [(blockhashes,start,end)..]
 
             # Every data entry in our list should now be share shnum for
             # a particular version of the mutable file, so all of the
@@ -1150,8 +1151,9 @@ class MutableFileVersion:
             datum = data[0]
             assert [x for x in data if x != datum] == []
 
+            # datum is (blockhashes,start,end)
             blockhashes[shnum] = datum[0]
-            start_segments[shnum] = datum[1]
+            start_segments[shnum] = datum[1] # (block,salt) bytestrings
             end_segments[shnum] = datum[2]
 
         d1 = r.decode(start_segments, self._start_segment)
diff --git a/src/allmydata/mutable/servermap.py b/src/allmydata/mutable/servermap.py
index 4daee5c0..10bb5b10 100644
--- a/src/allmydata/mutable/servermap.py
+++ b/src/allmydata/mutable/servermap.py
@@ -120,7 +120,10 @@ class ServerMap:
         self._bad_shares = {} # maps (server,shnum) to old checkstring
         self._last_update_mode = None
         self._last_update_time = 0
-        self.update_data = {} # (verinfo,shnum) => data
+        self.update_data = {} # shnum -> [(verinfo,(blockhashes,start,end)),..]
+        # where blockhashes is a list of bytestrings (the result of
+        # layout.MDMFSlotReadProxy.get_blockhashes), and start/end are both
+        # (block,salt) tuple-of-bytestrings from get_block_and_salt()
 
     def copy(self):
         s = ServerMap()
-- 
2.45.2