updating documentation

xtreemfs_client/dataDistribution.py

@@ -8,14 +8,17 @@ class DataDistribution(object):
     class to keep track of the osd (object storage device) locations of different folders, i.e.,
     their physical location.
 
-    this class also allows to calculate a 'good' osd for new data, based on the
-    distribution known beforehand.
+    this class also allows to calculate several data distributions, e.g., mappings from folders to OSDs (each folder
+    gets mapped to one OSD).
     """
 
     def __init__(self):
         self.OSDs = {}
 
     def add_new_osd(self, osd_uuid):
+        """
+        create a new empty osd and add it to the existing OSDs.
+        """
         if osd_uuid in self.OSDs:
             print("key: " + osd_uuid + " is already present!")
             return
@@ -23,30 +26,45 @@ class DataDistribution(object):
         self.OSDs[osd_uuid] = new_osd
 
     def add_osd(self, new_osd):
+        """
+        add the given OSD (object) to the existing OSDs.
+        """
         if new_osd.uuid in self.OSDs:
             print("key: " + new_osd.uuid + " is already present!")
             return
         self.OSDs[new_osd.uuid] = new_osd
 
     def add_osd_list(self, osd_list):
+        """
+        add the given list of OSDs (objects) to the existing OSDs.
+        """
         for osd_uuid in osd_list:
             if osd_uuid not in self.OSDs:
                 new_osd = osd.OSD(osd_uuid)
                 self.OSDs[osd_uuid] = new_osd
 
     def get_osd_list(self):
+        """
+        get a list of all existing OSDs.
+        """
         osd_list = []
         for osd_name in self.OSDs.keys():
             osd_list.append(osd_name)
         return osd_list
 
     def get_containing_osd(self, folder_id):
+        """
+        get the OSD containing the given folder_id, or None if the folder is not assigned to any OSD.
+        """
         for checked_osd in self.OSDs.values():
             if checked_osd.contains_folder(folder_id):
                 return checked_osd
         return None
 
     def get_average_folder_size(self):
+        """
+        get the average folder size of all folders of all OSDs.
+        """
         total_size = 0
         total_number_of_folders = 0
         for one_osd in self.OSDs.values():
@@ -57,6 +75,9 @@ class DataDistribution(object):
         return total_size / total_number_of_folders
 
     def assign_new_osd(self, folder_id, new_osd):
+        """
+        assign folder_id to new_osd. if folder_id already is assigned to an OSD, this old assignment is deleted.
+        """
         old_osd = self.get_containing_osd(folder_id)
         if old_osd is None:
             self.OSDs[new_osd].add_folder(folder_id, self.get_average_folder_size())
@@ -67,6 +88,7 @@ class DataDistribution(object):
     def add_folders(self, folders, osd_information=None, ratio_parameter='', random_osd_assignment=False):
         """
         adds a list of folders to the data distribution.
+        if not specified otherwise, the assignments are calculated using the LPT algorithm.
         returns a list of assignments from folders to OSDs, for which (folders) there was previously no assignment.
 
         if the optional arguments are given, OSDs are assigned data proportionally to their ratio_parameter.