added documentation to mainthread package explaining the worker queues; added documentation to BackgroundTask and BackgroundTaskThread

2 files changed, 56 insertions, 0 deletions

diff --git a/python/mainthread.py b/python/mainthread.py
index 14698b6a..9064a666 100644
--- a/python/mainthread.py
+++ b/python/mainthread.py
@@ -18,6 +18,41 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
+"""
+.. py:module:: mainthread
+
+This module provides two ways to execute "jobs":
+
+1. On the Binary Ninja main thread (the UI event thread when running in the GUI application):
+	* :py:func:`.execute_on_main_thread`
+	* :py:func:`.execute_on_main_thread_and_wait`
+2. On a worker thread
+
+Any manipulation of the GUI should be performed on the main thread, but any
+non-GUI work is generally better to be performed using a worker. This is
+especially true for any longer-running work, as the user interface will
+be unable to update itself while a job is executing on the main thread.
+
+There are three worker queues, in order of decreasing priority:
+
+	1. The Interactive Queue (:py:func:`.worker_interactive_enqueue`)
+	2. The Priority Queue (:py:func:`.worker_priority_enqueue`)
+	3. The Worker Queue (:py:func:`.worker_enqueue`)
+
+All of these queues are serviced by the same pool of worker threads. The
+difference between the queues is basically one of priority: one queue must
+be empty of jobs before a worker thread will execute a job from a lower
+priority queue.
+
+The default maximum number of concurrent worker threads is controlled by the
+`analysis.limits.workerThreadCount` setting but can be adjusted at runtime via
+:py:func:`.set_worker_thread_count`.
+
+The worker threads are native threads, managed by the Binary Ninja core. If
+more control over the thread is required, consider using the
+:py:class:`~binaryninja.plugin.BackgroundTaskThread` class.
+"""
+
 # Binary Ninja components
 from . import _binaryninjacore as core
 from . import scriptingprovider
diff --git a/python/plugin.py b/python/plugin.py
index e68e30d5..5a92215b 100644
--- a/python/plugin.py
+++ b/python/plugin.py
@@ -970,6 +970,18 @@ class _BackgroundTaskMetaclass(type):
 
 
 class BackgroundTask(metaclass=_BackgroundTaskMetaclass):
+	"""
+	The ``BackgroundTask`` class provides a mechanism for reporting progress of
+	an optionally cancelable task to the user via the status bar in the UI.
+	If ``can_cancel`` is is `True`, then the task can be cancelled either
+	programmatically (via :py:meth:`.cancel`) or by the user via the UI.
+
+	Note this class does not provide a means to execute a task, which is
+	available via the :py:class:`.BackgroundTaskThread` class.
+
+	:param initial_progress_text: text description of the task to display in the status bar in the UI, defaults to `""`
+	:param can_cancel: whether to enable cancelation of the task, defaults to `False`
+	"""
 	def __init__(self, initial_progress_text="", can_cancel=False, handle=None):
 		if handle is None:
 			self.handle = core.BNBeginBackgroundTask(initial_progress_text, can_cancel)
@@ -1022,6 +1034,15 @@ class BackgroundTask(metaclass=_BackgroundTaskMetaclass):
 
 
 class BackgroundTaskThread(BackgroundTask):
+	"""
+	The ``BackgroundTaskThread`` class provides an all-in-one solution for executing a :py:class:`.BackgroundTask`
+	in a thread.
+
+	See the :py:class:`.BackgroundTask` for additional information.
+
+	:param initial_progress_text: text description of the task to display in the status bar in the UI, defaults to `""`
+	:param can_cancel: whether to enable cancelation of the task, defaults to `False`
+	"""
 	def __init__(self, initial_progress_text: str = "", can_cancel: bool = False):
 		class _Thread(threading.Thread):
 			def __init__(self, task: 'BackgroundTaskThread'):