<p>You should probably do the code changes and doc changes in separate commits so they can be reverted separately. Generally, changes that do not depend on each other to work correctly should be separated for this reason. You should note the change to the code in the docs (in the same commit) then do the change to sphinx style in another commit.</p>

<div class="gmail_quote">On Dec 4, 2010 4:44 PM, "Sebastian Spaeth" <<a href="mailto:Sebastian@sspaeth.de">Sebastian@sspaeth.de</a>> wrote:<br type="attribution">> Rather than poll our exitthread Queue in a non-blocking fashion and<br>
> always sleep for 1 second inbetween, simply call it in a blocking<br>> fashion which will return immediately when a thread has exited. This<br>> is somewhat faster as we don't do unnecessary sleeps after a thread<br>
> exited.<br>> <br>> Do note that we need to specify some timeout value here (the 60 chosen<br>> is pretty arbitary, but what the value exactly is, is not that<br>> important, it could be any positive value) in order to make the<br>
> Queue.get() call work with SIGINT (cf<br>> <a href="http://bugs.python.org/issue1360">http://bugs.python.org/issue1360</a>).<br>> <br>> Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de><br>> ---<br>
> Reworded the commit message, I've kept the documentation style for now. If sphinx autogenerated-docs is not what people what, I can revert to plain old docs.<br>> <br>>  offlineimap/threadutil.py |   31 ++++++++++++++++++++-----------<br>
>  1 files changed, 20 insertions(+), 11 deletions(-)<br>> <br>> diff --git a/offlineimap/threadutil.py b/offlineimap/threadutil.py<br>> index c65700e..da7bcf6 100644<br>> --- a/offlineimap/threadutil.py<br>
> +++ b/offlineimap/threadutil.py<br>> @@ -101,22 +101,31 @@ def initexitnotify():<br>>      pass<br>>  <br>>  def exitnotifymonitorloop(callback):<br>> -    """Enter an infinite "monitoring" loop.  The argument, callback,<br>
> -    defines the function to call when an ExitNotifyThread has terminated.<br>> -    That function is called with a single argument -- the ExitNotifyThread<br>> -    that has terminated.  The monitor will not continue to monitor for<br>
> -    other threads until the function returns, so if it intends to perform<br>> -    long calculations, it should start a new thread itself -- but NOT<br>> -    an ExitNotifyThread, or else an infinite loop may result.  Furthermore,<br>
> -    the monitor will hold the lock all the while the other thread is waiting.<br>> +    """An infinite "monitoring" loop watching for finished ExitNotifyThread's.<br>> +<br>> +    :param callback: the function to call when a thread terminated. That <br>
> +                     function is called with a single argument -- the <br>> +                     ExitNotifyThread that has terminated. The monitor will <br>> +                     not continue to monitor for other threads until<br>
> +                     'callback' returns, so if it intends to perform long<br>> +                     calculations, it should start a new thread itself -- but<br>> +                     NOT an ExitNotifyThread, or else an infinite loop <br>
> +                     may result.<br>> +                     Furthermore, the monitor will hold the lock all the <br>> +                     while the other thread is waiting.<br>> +    :type callback:  a callable function<br>
>      """<br>>      global exitthreads<br>> -    while 1:                            # Loop forever.<br>> +    while 1:                            <br>> +        # Loop forever and call 'callback' for each thread that exited<br>
>          try:<br>> -            thrd = exitthreads.get(False)<br>> +            # we need a timeout in the get() call, so that ctrl-c can throw<br>> +            # a SIGINT (<a href="http://bugs.python.org/issue1360">http://bugs.python.org/issue1360</a>). A timeout with empty<br>
> +            # Queue will raise `Empty`.<br>> +            thrd = exitthreads.get(True, 60)<br>>              callback(thrd)<br>>          except Empty:<br>> -            time.sleep(1)<br>> +            pass<br>
>  <br>>  def threadexited(thread):<br>>      """Called when a thread exits."""<br>> -- <br>> 1.7.1<br>> <br>> <br>> _______________________________________________<br>
> OfflineIMAP-project mailing list<br>> <a href="mailto:OfflineIMAP-project@lists.alioth.debian.org">OfflineIMAP-project@lists.alioth.debian.org</a><br>> <a href="http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project">http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project</a><br>
> <br>> OfflineIMAP homepage: <a href="http://software.complete.org/offlineimap">http://software.complete.org/offlineimap</a><br></div>