Preliminary. ThinkMeta ConcurrentTasks and this documentation are preliminary; everything is subject to change.

The local scheduler

On this page

A Default scheduler runs tasks on threads of its own, and the thread that started the work only waits for it. A converted thread can wait on the primitives, but it is a single task. The local scheduler has no threads at all. Its tasks run inside Run, on the thread that calls it, and Run blocks that thread until every task has ended.

// A producer and a consumer take turns on the calling thread.
int SumOfSquares(int count)
{
    int         value = 0;
    int         sum   = 0;
    Semaphore_s filled;   // the consumer waits for the next value
    Semaphore_s taken{1}; // the producer waits until the value was taken

    auto producer = Task::Create([&] {
        for (int i = 1; i <= count; ++i) {
            taken.Wait();
            value = i * i;
            filled.Release();
        }
    });
    auto consumer = Task::Create([&] {
        for (int i = 1; i <= count; ++i) {
            filled.Wait();
            sum += value;
            taken.Release();
        }
    });

    LocalScheduler scheduler;
    producer.Schedule(scheduler);
    consumer.Schedule(scheduler);
    scheduler.Run(); // runs both tasks here; returns once both have ended
    return sum;
}

Both tasks run on the thread that called SumOfSquares. Each runs until it waits, then the other goes on. The semaphores, the tasks and the scheduler are local variables: Run returns only when no task is left that could still use them.

The examples on this page come from concept-local-scheduler.cpp, a complete program that checks its results. It uses these names:

#include <ThinkMeta.ConcurrentTasks/Core.h>
import ThinkMeta.ConcurrentTasks.Schedulers.LocalScheduler;
import ThinkMeta.ConcurrentTasks.Synchronization.Semaphore;
import ThinkMeta.ConcurrentTasks.Tasks.RunAndWait;
import ThinkMeta.ConcurrentTasks.Tasks.Task;

namespace TC = ThinkMeta::ConcurrentTasks;
using TC::Schedulers::LocalScheduler;
using TC::Synchronization::Semaphore_s;
using TC::Tasks::Task;

When to use it

  • The main thread works along. Local tasks hand work to the threads of a default scheduler and wait for it, and the calling thread runs the other local tasks meanwhile. A converted thread would block in its first wait.
  • Cooperative pipelines on one thread. Producers, consumers and generators that take turns, each written as a loop of its own. See Thinking in tasks.
  • A reproducible order, for tests and for teaching. As long as no other thread takes part, the tasks run in the same order every time, they can be stepped through in a debugger, and there are no data races.

The local scheduler is not built for speed. Its queues are those of the default scheduler, safe for any thread, also where only one thread is involved. It is about where tasks run.

How Run behaves

Schedulers::LocalScheduler creates the scheduler and owns it. Tasks are added with AddTask or Task::Schedule, before Run or by the tasks while it runs. Nothing runs until Run is called.

Situation What Run does
A task can run It runs the task, on the calling thread, until the task ends, waits or yields. Then it takes the next one.
Tasks are left, but all of them wait The thread sleeps until another thread, a timer or the completion of asynchronous I/O resumes one of them.
No task is left It returns.

A task counts from the moment it is added until it has exited. That includes tasks added by the scheduler's own tasks and tasks started by time (AddTimedTask): Run waits for their start and runs them.

Run may be called again: add tasks, run, add more, run again. A call with no tasks returns at once. Start and Stop do nothing, since Run decides when the scheduler works and when it is done.

The owning thread

The thread that calls Run owns the scheduler:

  • Only the owner adds tasks: before Run, and from the scheduler's tasks while it runs. Another thread cannot give a local scheduler new work. It can resume a task that waits, and that task can then add what is needed.
  • Run needs a plain thread, such as main. It must not be called from a task of any scheduler, nor on a converted thread: Run blocks its thread while all tasks wait, and a task must never block its thread.
  • The tasks stay on that thread. Unlike the tasks of a default scheduler, they never continue on another one, so they may use thread-bound state.

Working with other schedulers

A task of a local scheduler may be resumed from any thread. A local task can therefore hand work to a default scheduler and wait for the result, with Task::Schedule(scheduler), Tasks::RunAndWait or a TaskGroup_s. Timers (SleepTask, waits with a timeout) and asynchronous I/O work as on any scheduler.

// The calling thread computes one quarter itself; the workers compute the others.
long long SumWithWorkers(TC::ITaskScheduler& workers)
{
    long long sums[4] = {};

    auto handOver = [&](int quarter) {
        // Waits for the worker; the calling thread runs the other local tasks.
        TC::Tasks::RunAndWait(workers,
                              [&] { sums[quarter] = SumOfQuarter(quarter); });
        // Here the task is back on the thread that called Run.
    };
    auto first  = Task::Create([&] { handOver(0); });
    auto second = Task::Create([&] { handOver(1); });
    auto third  = Task::Create([&] { handOver(2); });
    auto own    = Task::Create([&] { sums[3] = SumOfQuarter(3); });

    LocalScheduler scheduler;
    Task*          tasks[] = {&first, &second, &third, &own};
    for (Task* task : tasks)
        task->Schedule(scheduler);
    scheduler.Run(); // returns once all four have ended
    return sums[0] + sums[1] + sums[2] + sums[3];
}

The first three tasks start, hand their quarter to the workers and wait. Then the calling thread computes the fourth quarter itself. When a worker has finished, the task that waited for it goes on, on the calling thread again: a suspended task always resumes on the scheduler that suspended it.

Warning

Run waits for the tasks of its own scheduler only. A task that runs on another scheduler is unknown to it. Let a local task wait for that work, as RunAndWait does here, or count the tasks into a TaskGroup_s and wait for the group in a local task.

In a local task, Task::Schedule without a scheduler adds to the local scheduler. Work for other threads needs its scheduler given explicitly.

The scheduler may be a local variable that goes right after Run, as in the examples: Run does not return while another thread that has just resumed one of its tasks is still at work inside the scheduler.

Order

The order is that of the default scheduler, so a program behaves the same on both. Run takes, in this order, a resumed High task, a new High task, a resumed Normal task and a new Normal task, and within each of the four the one that came first (Priorities). A task that yields goes behind the resumed tasks of its priority and before the new ones.

A task keeps the processor until it waits, yields or ends. If no other thread resumes a task, the order is fixed and the same in every run.

Limits

  • Speed. Every access to the queues is safe for other threads, whether or not another thread takes part. Do not expect a local scheduler to be faster than a default scheduler because only one thread is involved.
  • Queue capacity. As for the default scheduler, the number of tasks that can run at the same time is bounded per queue (see Queues and their capacity). The second parameter of the LocalScheduler constructor sets it. Waiting tasks do not count.
  • Stacks. A task gets its stack when it starts, not when it is added, so many tasks may be queued. The first constructor parameter sets the stack size.
  • One thread. A local scheduler cannot run inside a task, so it cannot be nested in another scheduler, and a worker thread or a UI handler cannot use one. A task that needs a group of tasks uses a TaskGroup on its own scheduler.

In the core, CreateLocalScheduler creates the scheduler and returns an ILocalScheduler. Of SchedulerInfo it uses taskQueueCapacity and taskStackSize and ignores the other fields.

Rules

Important

  • Call Run on a plain thread only: never from a task, never on a converted thread, and never on two threads at once.
  • Add tasks only on the thread that calls Run: before Run, or from the scheduler's tasks.
  • Do not let a local task wait for something that only the caller of Run provides: that thread is inside Run.
  • Do not block the thread in a local task (Sleep, a mutex, a blocking read): every other local task stands still meanwhile.
  • Destroy the scheduler after Run has returned and no task is left, on the same thread. A scheduler must not be destroyed by one of its own tasks.
  • Keep the tasks and everything they use alive until Run has returned.

See also