BackgroundThread

Detailed Description

Classes
class	BackgroundThread
	Helper class for running chains of actions on both the main thread and a background thread. More...

---

Class Documentation

BackgroundThread

class BackgroundThread

Helper class for running chains of actions on both the main thread and a background thread.

Especially useful for doing ui that also needs networking. Think of it like a JS-like promise chain except with more C++.

Example:

     // Passing `this` into create() will make the thread stop if `this` is deleted before it finishes.
     // Though note that `this` could still be deleted during a background action,
     // and the thread will only be stopped *after* the action is done, so you must be
     // sure to always guard data accessed in background actions with something like
     // a std::shared_ptr<T>.
     BackgroundThread::create(this)
     // Do actions serially in the background
     ->thenBackground([state = m_sharedPtrState](QVariant) {
         // Note that state should be accessed through a shared pointer-like structure
         // In case our parent gets deleted while we're doing background processing.
 
         // Do our task background here
         bool success = SomeLongNetworkOperation();
         // Return value will be passed to next action's QVariant parameter
         return success;
     })
     // And serially on the main thread
     ->thenMainThread([this](QVariant var) {
         // Retrieve value from last action
         bool success = var.value<bool>();
         UpdateUI(success);
         // You don't have to return anything (next QVariant param will be QVariant())
     })
     // You can also combine with a ProgressTask for showing a progress dialog
     ->thenBackgroundWithProgress(m_window, "Doing Task", "Please wait...", "Cancel", [state = m_sharedPtrState](QVariant var,
ProgressTask* task, ProgressFunction progress) {
         progress(0, 0);
         DoTask1WithProgress(SplitProgress(progress, 0, 1));
         // You can interface with the task itself
         task->setText("Doing Part 2");
         DoTask2WithProgress(SplitProgress(progress, 1, 1));
         progress(1, 1);
     })
     // You can combine with another BackgroundThread to do its actions after all of the
     // ones you have enqueued so far
     ->then(SomeOtherFunctionThatReturnsABackgroundThread())
     // If any then-action throws, all future then-actions will be ignored and the catch-actions will be run,
serially
     // NB: If a catch-action throws, the new exception will be passed to any further catch-actions
     ->catchMainThread([this](std::exception_ptr exc) {
         // So far the only way I've found to get the exception out:
         try
         {
             std::rethrow_exception(exc);
         }
         catch (std::exception e)
         {
             // Handle exception
         }
     })
     // You can also catch in the background
     ->catchBackground([state = m_sharedPtrState](std::exception_ptr exc) {
         ...
     })
     // Finally-actions will be run after all then-actions are finished
     // If a then-action throws, finally-actions will be run after all catch-actions are finished
     // NB: Finally-actions should not throw exceptions
     ->finallyMainThread([this](bool success) {
         if (success)
         {
             ReportSuccess();
         }
     })
     // You can also have finally-actions in the background
     ->finallyBackground([state = m_sharedPtrState](bool success) {
         ...
     })
     // Call start to start the thread
     ->start();

Public Types
typedef BinaryNinja::ProgressFunction	ProgressFunction
typedef std::function< QVariant(QVariant value)>	ThenFunction
typedef std::function< void(std::exception_ptr exc)>	CatchFunction
typedef std::function< void(bool success) >	FinallyFunction
Signals
void	done (QVariant result)
	Called when all functions have been run.
void	fail (std::exception_ptr exception)
	Called when an exception is thrown, after all catch functions have been run.
Public Member Functions
void	start (QVariant init=QVariant())
	Start the thread and run all its functions in sequence.
void	wait ()
	Block until the thread finishes.
BackgroundThread *	then (BackgroundThread *other)
	Add another BackgroundThread's functions to the end of this one's.
template<typename Func>
BackgroundThread *	thenBackground (Func &&func)
	Add a function to run on a background thread.
template<typename Func>
BackgroundThread *	thenMainThread (Func &&func)
	Add a function to run on the main thread.
template<typename Func>
BackgroundThread *	thenBackgroundWithProgress (QWidget *parent, const QString &title, const QString &text, const QString &cancel, Func &&func)
	Add a function to run on a background thread, with a progress dialog that blocks the main thread while it runs.
BackgroundThread *	catchBackground (CatchFunction func)
	Add a function to run on a background thread in the event an exception is thrown.
BackgroundThread *	catchMainThread (CatchFunction func)
	Add a function to run on the main thread in the event an exception is thrown.
BackgroundThread *	finallyBackground (FinallyFunction func)
	Add a function to run on a background thread after all other functions, even if something threw.
BackgroundThread *	finallyMainThread (FinallyFunction func)
	Add a function to run on the main thread after all other functions, even if something threw.
Static Public Member Functions
static BackgroundThread *	create (QObject *owner=nullptr)
	Create a new background thread (but don't start it).

Member Typedef Documentation

ProgressFunction

typedef BinaryNinja::ProgressFunction BackgroundThread::ProgressFunction

ThenFunction

typedef std::function<QVariant(QVariant value)> BackgroundThread::ThenFunction

CatchFunction

typedef std::function<void(std::exception_ptr exc)> BackgroundThread::CatchFunction

FinallyFunction

typedef std::function<void(bool success) > BackgroundThread::FinallyFunction

Member Function Documentation

create()

BackgroundThread * BackgroundThread::create ( QObject * owner = nullptr )

inlinestatic

Create a new background thread (but don't start it).

Parameters

owner

QObject that "owns" the thread (or nullptr). If this owner is destroyed, the thread will be terminated before the next callback.

Returns

Empty thread with no functions

start()

void BackgroundThread::start ( QVariant init = QVariant() )

inline

Start the thread and run all its functions in sequence.

Parameters

init	Argument for first function in the thread

wait()

void BackgroundThread::wait ( )

inline

Block until the thread finishes.

then()

BackgroundThread * BackgroundThread::then ( BackgroundThread * other )

inline

Add another BackgroundThread's functions to the end of this one's.

Will move functions out of `other`

Parameters

other

BackgroundThread whose functions will be used

Returns

This BackgroundThread

thenBackground()

template<typename Func>

BackgroundThread * BackgroundThread::thenBackground ( Func && func )

inline

Add a function to run on a background thread.

Parameters

func	Function to run on background thread

Returns

This BackgroundThread

thenMainThread()

template<typename Func>

BackgroundThread * BackgroundThread::thenMainThread ( Func && func )

inline

Add a function to run on the main thread.

Parameters

func	Function to run on main thread

Returns

This BackgroundThread

thenBackgroundWithProgress()

template<typename Func>

BackgroundThread * BackgroundThread::thenBackgroundWithProgress ( QWidget * parent, const QString & title, const QString & text, const QString & cancel, Func && func )

inline

Add a function to run on a background thread, with a progress dialog that blocks the main thread while it runs.

Parameters

parent	Parent widget for progress dialog
title	Title of progress dialog
text	Text of progress dialog
cancel	Cancel button text for progress dialog
func	Function to run on background thread, [QVariant|void](QVariant, ProgressTask*, ProgressFunction)

Returns

This BackgroundThread

catchBackground()

BackgroundThread * BackgroundThread::catchBackground ( CatchFunction func )

inline

Add a function to run on a background thread in the event an exception is thrown.

Parameters

func	Function to run on background thread

Returns

This BackgroundThread

catchMainThread()

BackgroundThread * BackgroundThread::catchMainThread ( CatchFunction func )

inline

Add a function to run on the main thread in the event an exception is thrown.

Parameters

func	Function to run on main thread

Returns

This BackgroundThread

finallyBackground()

BackgroundThread * BackgroundThread::finallyBackground ( FinallyFunction func )

inline

Add a function to run on a background thread after all other functions, even if something threw.

Parameters

func	Function to run on background thread

Returns

This BackgroundThread

finallyMainThread()

BackgroundThread * BackgroundThread::finallyMainThread ( FinallyFunction func )

inline

Add a function to run on the main thread after all other functions, even if something threw.

Parameters

func	Function to run on main thread

Returns

This BackgroundThread

done

void BackgroundThread::done ( QVariant result )

signal

Called when all functions have been run.

Parameters

result

Final result

fail

void BackgroundThread::fail ( std::exception_ptr exception )

signal

Called when an exception is thrown, after all catch functions have been run.

Parameters

exception

Thrown exception