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 c4d7dd01140d99609452a05eabcf83e9d6376c58..853a6f76243925e330b6b3fa7dea743c2b40c114 100644 (file)
--- 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 4b7a00590aedd5a830a67e5ef8571ec176a60a57..8561ab4509bc31c813c0084e75964a49d41d1b07 100644 (file)
--- 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 c7fa82f6a4193bff7bdb702b3807f49ec7953fc5..6d961e995fc08f753960c8ad4f8e70ef92d44db8 100644 (file)
--- 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