Add some comments to the db manager async code

Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de>

1 files changed, 21 insertions, 0 deletions

diff --git a/alot/db/manager.py b/alot/db/manager.py
index 99ae607c..b3d31694 100644
--- a/alot/db/manager.py
+++ b/alot/db/manager.py
@@ -34,18 +34,29 @@ class FillPipeProcess(multiprocessing.Process):
         self.stderr = stderr
 
     def handle_sigterm(self, signo, frame):
+        # this is used to suppress any EINTR errors at interpreter
+        # shutdown
         self.keep_going = False
+
+        # raises SystemExit to shut down the interpreter from the
+        # signal handler
         sys.exit()
 
     def run(self):
+        # replace filedescriptors 1 and 2 (stdout and stderr) with
+        # pipes to the parent process
         os.dup2(self.stdout, 1)
         os.dup2(self.stderr, 2)
+
+        # register a signal handler for SIGTERM
         signal.signal(signal.SIGTERM, self.handle_sigterm)
 
         for a in self.it:
             try:
                 self.pipe.send(self.fun(a))
             except IOError as e:
+                # suppress spurious EINTR errors at interpreter
+                # shutdown
                 if e.errno != errno.EINTR or self.keep_going:
                     raise
 
@@ -313,16 +324,22 @@ class DBManager(object):
         :rtype: (:class:`multiprocessing.Pipe`,
                 :class:`multiprocessing.Process`)
         """
+        # create two unix pipes to redirect the workers stdout and
+        # stderr
         stdout = os.pipe()
         stderr = os.pipe()
+
+        # create a multiprocessing pipe for the results
         pipe = multiprocessing.Pipe(False)
         receiver, sender = pipe
+
         process = FillPipeProcess(cbl(), stdout[1], stderr[1], pipe, fun)
         process.start()
         self.processes.append(process)
         logging.debug('Worker process {0} spawned'.format(process.pid))
 
         def threaded_wait():
+            # wait(2) for the process to die
             process.join()
 
             if process.exitcode < 0:
@@ -335,6 +352,8 @@ class DBManager(object):
             logging.debug('Worker process {0} {1}'.format(process.pid, msg))
             self.processes.remove(process)
 
+        # spawn a thread to collect the worker process once it dies
+        # preventing it from hanging around as zombie
         reactor.callInThread(threaded_wait)
 
         def threaded_reader(prefix, fd):
@@ -343,6 +362,8 @@ class DBManager(object):
                     logging.debug('Worker process {0} said on {1}: {2}'.format(
                             process.pid, prefix, line.rstrip()))
 
+        # spawn two threads that read from the stdout and stderr pipes
+        # and write anything that appears there to the log
         reactor.callInThread(threaded_reader, 'stdout', stdout[0])
         os.close(stdout[1])
         reactor.callInThread(threaded_reader, 'stderr', stderr[0])