b.c.CatchingExceptionThread(threading.Thread) : class documentation

Part of bzrlib.cethread View In Hierarchy

Known subclasses: bzrlib.tests.test_server.TestThread

A thread that keeps track of exceptions.

If an exception occurs during the thread execution, it's caught and re-raised when the thread is joined().

Method __init__ Undocumented
Method set_sync_event Set the sync_event event used to synchronize exception catching.
Method switch_and_set Switch to a new sync_event and set the current one.
Method set_ignored_exceptions Declare which exceptions will be ignored.
Method run Overrides Thread.run to capture any exception.
Method join Overrides Thread.join to raise any exception caught.
Method pending_exception Raise the caught exception.
def __init__(self, *args, **kwargs):
Undocumented
def set_sync_event(self, event):
Set the sync_event event used to synchronize exception catching.

When the thread uses an event to synchronize itself with another thread (setting it when the other thread can wake up from a wait call), the event must be set after catching an exception or the other thread will hang.

Some threads require multiple events and should set the relevant one when appropriate.

Note that the event should be initially cleared so the caller can wait() on him and be released when the thread set the event.

Also note that the thread can use multiple events, setting them as it progress, while the caller can chose to wait on any of them. What matters is that there is always one event set so that the caller is always released when an exception is caught. Re-using the same event is therefore risky as the thread itself has no idea about which event the caller is waiting on. If the caller has already been released then a cleared event won't guarantee that the caller is still waiting on it.

def switch_and_set(self, new):
Switch to a new sync_event and set the current one.

Using this method protects against race conditions while setting a new sync_event.

Note that this allows a caller to wait either on the old or the new event depending on whether it wants a fine control on what is happening inside a thread.

ParametersnewThe event that will become sync_event
def set_ignored_exceptions(self, ignored):
Declare which exceptions will be ignored.
Parametersignored

Can be either:

  • None: all exceptions will be raised,
  • an exception class: the instances of this class will be ignored,
  • a tuple of exception classes: the instances of any class of the list will be ignored,
  • a callable: that will be passed the exception object and should return True if the exception should be ignored
def run(self):
Overrides Thread.run to capture any exception.
def join(self, timeout=None):
Overrides Thread.join to raise any exception caught.

Calling join(timeout=0) will raise the caught exception or return None if the thread is still alive.

def pending_exception(self):
Raise the caught exception.

This does nothing if no exception occurred.

API Documentation for Bazaar, generated by pydoctor at 2014-09-02 00:02:07.