diff options
Diffstat (limited to 'python')
| -rw-r--r-- | python/mainthread.py | 35 | ||||
| -rw-r--r-- | python/plugin.py | 21 |
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'): |