From: Daira Hopwood <daira@jacaranda.org>
Date: Thu, 5 Sep 2013 18:16:27 +0000 (+0100)
Subject: Mon Jul  2 00:08:43 BST 2012  david-sarah@jacaranda.org
X-Git-Url: https://git.rkrishnan.org/specifications/%5B/%5D%20//%22%22?a=commitdiff_plain;h=1fcaa5d37ce24b36a731fd75053e167f18026762;p=tahoe-lafs%2Ftahoe-lafs.git

Mon Jul  2 00:08:43 BST 2012  david-sarah@jacaranda.org
  * [1.9.2 branch] Add comments and a caveat in webapi.rst indicating that the needs-rebalancing field may be computed incorrectly. refs #1115 refs #1784
---

diff --git a/docs/frontends/webapi.rst b/docs/frontends/webapi.rst
index c4d7dd01..853a6f76 100644
--- a/docs/frontends/webapi.rst
+++ b/docs/frontends/webapi.rst
@@ -1347,7 +1347,9 @@ mainly intended for developers.
     count-shares-needed: 'k', the number of shares required for recovery
     count-shares-expected: 'N', the number of total shares generated
     count-good-share-hosts: the number of distinct storage servers with good
-                            shares
+                            shares. Note that a high value does not necessarily
+                            imply good share distribution, because some of
+                            these servers may only hold duplicate shares.
     count-wrong-shares: for mutable files, the number of shares for
                         versions other than the 'best' one (highest
                         sequence number, highest roothash). These are
@@ -1362,10 +1364,12 @@ mainly intended for developers.
     list-corrupt-shares: a list of "share locators", one for each share
                          that was found to be corrupt. Each share locator
                          is a list of (serverid, storage_index, sharenum).
-    needs-rebalancing: (bool) True if there are multiple shares on a single
-                       storage server, indicating a reduction in reliability
-                       that could be resolved by moving shares to new
-                       servers.
+    needs-rebalancing: (bool) This field is intended to be True iff
+                       reliability could be improved for this file by
+                       rebalancing, i.e. by moving some shares to other
+                       servers. It is not guaranteed to be computed correctly
+                       in Tahoe-LAFS up to and including v1.9.2, and its
+                       precise definition may change in future versions.
     servers-responding: list of base32-encoded storage server identifiers,
                         one for each server which responded to the share
                         query.
diff --git a/src/allmydata/immutable/checker.py b/src/allmydata/immutable/checker.py
index 4b7a0059..8561ab45 100644
--- a/src/allmydata/immutable/checker.py
+++ b/src/allmydata/immutable/checker.py
@@ -796,6 +796,7 @@ class Checker(log.PrefixingLogMixin):
         # The file needs rebalancing if the set of servers that have at least
         # one share is less than the number of uniquely-numbered shares
         # available.
+        # TODO: this may be wrong, see ticket #1115 comment:27 and ticket #1784.
         cr.set_needs_rebalancing(d['count-good-share-hosts'] < d['count-shares-good'])
 
         cr.set_data(d)
diff --git a/src/allmydata/immutable/filenode.py b/src/allmydata/immutable/filenode.py
index c7fa82f6..6d961e99 100644
--- a/src/allmydata/immutable/filenode.py
+++ b/src/allmydata/immutable/filenode.py
@@ -131,6 +131,8 @@ class CiphertextFileNode:
                     prr.set_healthy(is_healthy)
                     prr.set_recoverable(is_recoverable)
                     crr.repair_successful = is_healthy
+
+                    # TODO: this may be wrong, see ticket #1115 comment:27 and ticket #1784.
                     prr.set_needs_rebalancing(len(sm) >= verifycap.total_shares)
 
                     crr.post_repair_results = prr