Template Class Job¶

Defined in File job.h

Inheritance Relationships¶

Base Type¶

public portal::JobBase (Class JobBase)

Class Documentation¶

template<typename Result = void> class Job : public portal::JobBase ¶

C++20 coroutine type for asynchronous parallel work with optional return value.

Job<T> is the primary coroutine type for the Portal Framework’s work-stealing scheduler. Jobs integrate with the Scheduler for parallel execution, support nested parallelism via co_await, and participate in fork-join synchronization via Counter.

Lifecycle:

Job created suspended (via co_return from job function)
Dispatched to Scheduler via wait_for_job() or dispatch_job()
Executed on worker thread (may suspend/resume on different threads)
Result retrieved via result() or automatic in co_await

Thread Safety:

Jobs can migrate between worker threads when suspended/resumed
Result storage is thread-safe (accessed only after completion)
Multiple threads can co_await the same job (scheduler handles synchronization)

Example (Simple Job):

Job<int> compute_sum(int a, int b)
{
    co_return a + b;
}

auto result = scheduler.wait_for_job(compute_sum(10, 32)); // result = 42

Example (Nested Jobs - Parent/Child):

Job<int> child_work(int value)
{
    // Simulate work
    co_return value * 2;
}

Job<int> parent_work()
{
    // Dispatch child and co_await result
    auto child = child_work(21);
    int child_result = co_await child; // Suspends parent, child executes, parent resumes with result
    co_return child_result; // Returns 42
}

auto final = scheduler.wait_for_job(parent_work());

Example (Fork-Join Parallelism):

Job<void> process_chunk(int chunk_id)
{
    // Process chunk...
    co_return;
}

Job<void> parallel_process()
{
    Counter counter{};

    // Dispatch 4 jobs in parallel
    for (int i = 0; i < 4; i++)
        scheduler.dispatch_job(process_chunk(i), JobPriority::Normal, &counter); // Counter is automatically incremented

    // Wait for all chunks to complete
    scheduler.wait_for_counter(&counter);

    co_return;
}