Classes
BackgroundThread
C++ UI API

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.
BackgroundThread::create(this)
// Do actions serially in the background
->thenBackground([this](QVariant) {
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", [this](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([this](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([this](bool success) {
...
})
// Call start to start the thread
->start();
BackgroundThread::thenBackgroundWithProgress
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 whil...
Definition: progresstask.h:554
BackgroundThread::thenBackground
BackgroundThread * thenBackground(Func &&func)
Add a function to run on a background thread.
Definition: progresstask.h:526
BackgroundThread::ProgressFunction
std::function< bool(size_t, size_t)> ProgressFunction
Definition: progresstask.h:274
BackgroundThread::then
BackgroundThread * then(BackgroundThread *other)
Add another BackgroundThread's functions to the end of this one's.
Definition: progresstask.h:499
BackgroundThread::catchBackground
BackgroundThread * catchBackground(CatchFunction func)
Add a function to run on a background thread in the event an exception is thrown.
Definition: progresstask.h:615
BackgroundThread::catchMainThread
BackgroundThread * catchMainThread(CatchFunction func)
Add a function to run on the main thread in the event an exception is thrown.
Definition: progresstask.h:626
BackgroundThread::finallyMainThread
BackgroundThread * finallyMainThread(FinallyFunction func)
Add a function to run on the main thread after all other functions, even if something threw.
Definition: progresstask.h:648
BackgroundThread::finallyBackground
BackgroundThread * finallyBackground(FinallyFunction func)
Add a function to run on a background thread after all other functions, even if something threw.
Definition: progresstask.h:637
BackgroundThread::start
void start(QVariant init=QVariant())
Start the thread and run all its functions in sequence.
Definition: progresstask.h:446
BackgroundThread::create
static BackgroundThread * create(QObject *owner=nullptr)
Create a new background thread (but don't start it)
Definition: progresstask.h:436
BackgroundThread::thenMainThread
BackgroundThread * thenMainThread(Func &&func)
Add a function to run on the main thread.
Definition: progresstask.h:538
ProgressTask::setText
void setText(const QString &text)
Set the text label on the progress dialog.
ProgressTask
Wrapper around QThread and ProgressDialog that runs a task in the background, providing updates to th...
Definition: progresstask.h:106
BinaryNinja::SplitProgress
std::function< bool(size_t, size_t)> SplitProgress(std::function< bool(size_t, size_t)> originalFn, size_t subpart, size_t subpartCount)
Split a single progress function into equally sized subparts.
Definition: binaryninjaapi.cpp:386

Public Types

typedef std::function< bool(size_t, size_t)> 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. More...
 
void fail (std::exception_ptr exception)
 Called when an exception is thrown, after all catch functions have been run. More...
 

Public Member Functions

void start (QVariant init=QVariant())
 Start the thread and run all its functions in sequence. More...
 
void wait ()
 Block until the thread finishes. More...
 
BackgroundThread * then (BackgroundThread *other)
 Add another BackgroundThread's functions to the end of this one's. More...
 
template<typename Func >
BackgroundThread * thenBackground (Func &&func)
 Add a function to run on a background thread. More...
 
template<typename Func >
BackgroundThread * thenMainThread (Func &&func)
 Add a function to run on the main thread. More...
 
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. More...
 
BackgroundThread * catchBackground (CatchFunction func)
 Add a function to run on a background thread in the event an exception is thrown. More...
 
BackgroundThread * catchMainThread (CatchFunction func)
 Add a function to run on the main thread in the event an exception is thrown. More...
 
BackgroundThread * finallyBackground (FinallyFunction func)
 Add a function to run on a background thread after all other functions, even if something threw. More...
 
BackgroundThread * finallyMainThread (FinallyFunction func)
 Add a function to run on the main thread after all other functions, even if something threw. More...
 

Static Public Member Functions

static BackgroundThread * create (QObject *owner=nullptr)
 Create a new background thread (but don't start it) More...
 

Member Typedef Documentation

◆ ProgressFunction

typedef std::function<bool(size_t, size_t)> 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()

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

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

Parameters
ownerQObject 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
initArgument 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
otherBackgroundThread 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
funcFunction 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
funcFunction 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
parentParent widget for progress dialog
titleTitle of progress dialog
textText of progress dialog
cancelCancel button text for progress dialog
funcFunction 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
funcFunction 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
funcFunction 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
funcFunction 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
funcFunction to run on main thread
Returns
This BackgroundThread

◆ done

void BackgroundThread::done ( QVariant  result)
signal

Called when all functions have been run.

Parameters
resultFinal result

◆ fail

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

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

Parameters
exceptionThrown exception