Saturday, November 21, 2026

A C++ serial task executor - influenced by earlier Android AsyncTask's serialexecutor...

AI-generated content but worth the effort...

This project is a C++20 re-creation of early Android AsyncTask (SERIAL_EXECUTOR): background work runs strictly one task at a time in FIFO order on a dedicated worker thread, while UI/progress/completion callbacks are marshaled back to a main/UI thread loop so you don't race on UI state.


High-Level Architecture & Threading Model


There are two distinct threads in the application:
  1. Main / UI Thread (main.cpp + MainThreadLoop)

    • Starts tasks via task.execute(params), triggering onPreExecute() immediately on the caller thread.

    • Drains queued UI callbacks (onProgressUpdate, onPostExecute) inside MainThreadLoop::pumpUntil(...).

  2. Background Worker Thread (SerialExecutor)

    • Owns a single std::thread (worker_) and a FIFO queue (std::deque<std::function<void()>>).

    • Executes one background callable to completion before popping the next one.

Plaintext
Main / UI Thread                          SerialExecutor Worker Thread
───────────────────                       ────────────────────────────
task1.execute(url1)
  └─▶ onPreExecute()  ──(enqueues)──▶ [ url1 task ]  ──▶ doInBackground(url1)
task2.execute(url2)                                        ├─ publishProgress() ──┐
  └─▶ onPreExecute()  ──(enqueues)──▶ [ url2 task ]  ◀─┘  (waits for url1)    │
                                                                               ▼
pumpUntil(...) ◀──────────────(posts callbacks)──────────────────── [ MainThreadLoop ]
  ├─ onProgressUpdate(25%, 50%...)                                     queue
  └─ onPostExecute(result)
       └─ ++completed; notifyWake()


Component-by-Component Breakdown


A. SerialExecutor (SerialExecutor.h / SerialExecutor.cpp)

  • FIFO Queue + Synchronization: Protects queue_ and stopping_ with a std::mutex, using std::condition_variable (cv_) so the worker sleeps with zero CPU spin when idle and wakes immediately when a task arrives or shutdown begins.

  • Why std::deque? Efficient O(1) push at the back (push_back) and O(1) pop at the front (pop_front), matching Android's ArrayDeque FIFO behavior.

  • Exception Containment: runLoop() wraps next_task() in try / catch (std::exception) and catch (...). If one background task throws, the worker logs it and keeps running subsequent tasks rather than terminating the thread and leaving queued work stuck forever.

  • Graceful Shutdown: shutdown() sets stopping_ = true under the lock, calls cv_.notify_all(), and joins worker_. Any task already queued before shutdown() is still drained before runLoop() exits; execute() rejects new tasks once stopping.


B. MainThreadLoop (MainThreadLoop.h / MainThreadLoop.cpp)

  • Acts as a lightweight stand-in for Android's Looper / Handler.

  • post(callback): Thread-safe producer method. Background threads (or any thread) push UI callbacks onto callbacks_ and call cv_.notify_one().

  • pumpUntil(should_stop): Runs on the main thread. Waits until either callbacks_ is non-empty or should_stop() returns true. It drains callbacks one at a time on the calling thread, exiting only once the queue is empty and should_stop() is true.

  • notifyWake(): Calls cv_.notify_all() to re-evaluate the condition variable predicate—essential when should_stop() depends on an external atomic counter (completed.load() >= 2) updated inside a callback.


C. AsyncTask<Params, Progress, Result> (async_task.h)

  • Template Parameters:

    • Params: Input passed to execute() and doInBackground().

    • Progress: Type passed to publishProgress() and received by onProgressUpdate().

    • Result: Return value of doInBackground() and input to onPostExecute().

  • Lifecycle Flow in execute(Params params):

    1. Calls onPreExecute() synchronously on the caller/UI thread.

    2. Enqueues a lambda onto SerialExecutor that runs doInBackground(std::move(p)) on the worker thread.

    3. Inside doInBackground, subclasses can call publishProgress(pct), which posts a lambda to MainThreadLoop so onProgressUpdate runs on the UI thread.

    4. Once doInBackground returns res, another lambda is posted to MainThreadLoop to invoke onPostExecute(std::move(res)) on the UI thread.


D. DownloadTask & main() (main.cpp)

  • DownloadTask specializes AsyncTask<std::string, int, std::string>, simulating progress steps (25, 50, 75, 100) every 150 ms.

  • Because SerialExecutor has only one worker thread, task2 starts only after task1 finishes doInBackground—even though both onPreExecute() calls run right away.

  • main() pumps MainThreadLoop until completed reaches 2, then shuts down SerialExecutor cleanly.


The Source Code...


MainThreadLoop.h
#pragma once

#include <condition_variable>
#include <deque>
#include <functional>
#include <mutex>

class MainThreadLoop {
public:
void post(std::function<void()> callback);

// Drains callbacks until `should_stop()` returns true and the queue is empty.
void pumpUntil(const std::function<bool()>& should_stop);
void notifyWake();

private:
std::mutex mutex_;
std::condition_variable cv_;
std::deque<std::function<void()>> callbacks_;
};

MainThreadLoop.cpp
#include "MainThreadLoop.h"

#include <utility>

void MainThreadLoop::post(std::function<void()> callback) {
if (!callback) {
return;
}
{
std::lock_guard<std::mutex> lock(mutex_);
callbacks_.push_back(std::move(callback));
}
cv_.notify_one();
}

void MainThreadLoop::pumpUntil(const std::function<bool()>& should_stop) {
while (true) {
std::function<void()> cb;
{
std::unique_lock<std::mutex> lock(mutex_);
cv_.wait(lock, [this, &should_stop] {
return !callbacks_.empty() || (should_stop && should_stop());
});

if (callbacks_.empty() && should_stop && should_stop()) {
return;
}

if (!callbacks_.empty()) {
cb = std::move(callbacks_.front());
callbacks_.pop_front();
}
}
if (cb) {
cb();
}
}
}

void MainThreadLoop::notifyWake() {
cv_.notify_all();
}

SerialExecutor.h
#pragma once

#include <condition_variable>
#include <deque>
#include <functional>
#include <mutex>
#include <thread>

class SerialExecutor {
public:
SerialExecutor();
~SerialExecutor();

SerialExecutor(const SerialExecutor&) = delete;
SerialExecutor& operator=(const SerialExecutor&) = delete;

void execute(std::function<void()> task);
void shutdown();

private:
void runLoop();

std::mutex mutex_;
std::condition_variable cv_;
std::deque<std::function<void()>> queue_;
bool stopping_ = false;
std::thread worker_;
};

SerialExecutor.cpp
#include "SerialExecutor.h"

#include <exception>
#include <iostream>
#include <utility>

SerialExecutor::SerialExecutor()
: worker_([this] { runLoop(); }) {}

SerialExecutor::~SerialExecutor() {
shutdown();
}

void SerialExecutor::execute(std::function<void()> task) {
if (!task) {
return;
}
{
std::lock_guard<std::mutex> lock(mutex_);
if (stopping_) {
return;
}
queue_.push_back(std::move(task));
}
cv_.notify_one();
}

void SerialExecutor::shutdown() {
{
std::lock_guard<std::mutex> lock(mutex_);
if (stopping_) {
return;
}
stopping_ = true;
}
cv_.notify_all();
if (worker_.joinable()) {
worker_.join();
}
}

void SerialExecutor::runLoop() {
while (true) {
std::function<void()> next_task;
{
std::unique_lock<std::mutex> lock(mutex_);
cv_.wait(lock, [this] {
return stopping_ || !queue_.empty();
});

if (queue_.empty() && stopping_) {
return;
}

next_task = std::move(queue_.front());
queue_.pop_front();
}

try {
next_task();
} catch (const std::exception& ex) {
std::cerr << "[SerialExecutor] Task threw: " << ex.what() << "\n";
} catch (...) {
std::cerr << "[SerialExecutor] Task threw unknown exception\n";
}
}
}

Asynctask.h

#pragma once

#include "MainThreadLoop.h"
#include "SerialExecutor.h"

#include <utility>

template <typename Params, typename Progress, typename Result>
class AsyncTask {
public:
AsyncTask(SerialExecutor& executor, MainThreadLoop& main_loop)
: executor_(executor), main_loop_(main_loop) {}

virtual ~AsyncTask() = default;

AsyncTask(const AsyncTask&) = delete;
AsyncTask& operator=(const AsyncTask&) = delete;

void execute(Params params) {
onPreExecute();

executor_.execute([this, p = std::move(params)]() mutable {
Result res = doInBackground(std::move(p));
main_loop_.post([this, r = std::move(res)]() mutable {
onPostExecute(std::move(r));
});
});
}

protected:
virtual void onPreExecute() {}
virtual Result doInBackground(Params params) = 0;
virtual void onProgressUpdate(const Progress& progress) {}
virtual void onPostExecute(Result result) {}

void publishProgress(Progress progress) {
main_loop_.post([this, prog = std::move(progress)]() {
onProgressUpdate(prog);
});
}

private:
SerialExecutor& executor_;
MainThreadLoop& main_loop_;
};

Main.cpp

#include "AsyncTask.h"
#include "MainThreadLoop.h"
#include "SerialExecutor.h"

#include <atomic>
#include <chrono>
#include <iostream>
#include <string>
#include <thread>

class DownloadTask : public AsyncTask<std::string, int, std::string> {
public:
DownloadTask(SerialExecutor& exec,
MainThreadLoop& ui,
std::atomic<int>& completed_counter)
: AsyncTask(exec, ui),
ui_(ui),
completed_counter_(completed_counter) {}

protected:
void onPreExecute() override {
std::cout << "[UI] Starting download task...\n";
}

std::string doInBackground(std::string url) override {
for (int pct : {25, 50, 75, 100}) {
std::this_thread::sleep_for(std::chrono::milliseconds(150));
publishProgress(pct);
}
return "Downloaded: " + url;
}

void onProgressUpdate(const int& progress) override {
std::cout << "[UI] Progress: " << progress << "%\n";
}

void onPostExecute(std::string result) override {
std::cout << "[UI] Done -> " << result << "\n";
++completed_counter_;
ui_.notifyWake();
}

private:
MainThreadLoop& ui_;
std::atomic<int>& completed_counter_;
};

int main() {
SerialExecutor serial_executor;
MainThreadLoop main_loop;
std::atomic<int> completed{0};

DownloadTask task1(serial_executor, main_loop, completed);
DownloadTask task2(serial_executor, main_loop, completed);

task1.execute("https://example.com/file1.zip");
task2.execute("https://example.com/file2.zip");

main_loop.pumpUntil([&completed] {
return completed.load() >= 2;
});

serial_executor.shutdown();
return 0;
}

CMakeLists.txt

cmake_minimum_required(VERSION 4.4)
project(SerialTaskExecutor LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Threads REQUIRED)

add_executable(SerialTaskExecutor main.cpp
SerialExecutor.cpp
SerialExecutor.h
MainThreadLoop.cpp
MainThreadLoop.h
AsyncTask.h)

target_link_libraries(SerialTaskExecutor PRIVATE Threads::Threads)

Result...

[UI] Starting download task...
[UI] Starting download task...
[UI] Progress: 25%
[UI] Progress: 50%
[UI] Progress: 75%
[UI] Progress: 100%
[UI] Done -> Downloaded: https://example.com/file1.zip
[UI] Progress: 25%
[UI] Progress: 50%
[UI] Progress: 75%
[UI] Progress: 100%
[UI] Done -> Downloaded: https://example.com/file2.zip