From: Mukund Sivaraman <muks@isc.org>
Date: Sun, 23 Jun 2013 18:35:40 +0000 (+0530)
Subject: [2855] Add class documentation
X-Git-Tag: bind10-1.2.0beta1-release~371^2~9
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=c3ef6db1a2b58b3732f1d2aa169127ade79fcb77;p=thirdparty%2Fkea.git

[2855] Add class documentation
---

diff --git a/src/lib/python/isc/memmgr/builder.py b/src/lib/python/isc/memmgr/builder.py
index c1970d6c0f..86ece0f1aa 100644
--- a/src/lib/python/isc/memmgr/builder.py
+++ b/src/lib/python/isc/memmgr/builder.py
@@ -20,6 +20,29 @@ class MemorySegmentBuilder:
     """
 
     def __init__(self, sock, cv, lock, command_queue, response_queue):
+        """ The constructor takes the following arguments:
+
+            sock: A socket using which this builder object notifies the
+                  main thread that it has a response waiting for it.
+
+            cv: A condition variable object that is used by the main
+                thread to tell this builder object that new commands are
+                available to it.
+
+            lock: A lock object which should be acquired before using or
+                  modifying the contents of command_queue and
+                  response_queue.
+
+            command_queue: A list of commands sent by the main thread to
+                           this object. Commands should be executed
+                           sequentially in the given order by this
+                           object.
+
+            response_queue: A list of responses sent by this object to
+                            the main thread. The format of this is
+                            currently undefined.
+        """
+
         self._sock = sock
         self._cv = cv
         self._lock = lock
@@ -28,6 +51,16 @@ class MemorySegmentBuilder:
         self._shutdown = False
 
     def run(self):
+        """ This is the method invoked when the builder thread is
+            started.  In this thread, be careful when modifying
+            variables passed-by-reference in the constructor. If they are
+            reassigned, they will not refer to the main thread's objects
+            any longer. Any use of command_queue and response_queue must
+            be synchronized by acquiring the lock. This method must
+            normally terminate only when the 'shutdown' command is sent
+            to it.
+        """
+
         with self._cv:
             while not self._shutdown:
                 while len(self._command_queue) == 0: