src/docs/threading_and_tasks_faq.md

Threading and Tasks in Chrome - FAQ

[TOC]

Note: Make sure to read the main Threading and Tasks docs first.

General

On which thread will a task run?

A task is posted through the base/task/post_task.h API with TaskTraits.

• If TaskTraits contain BrowserThread::UI:

  • The task runs on the main thread.

• If TaskTraits contain BrowserThread::IO:

  • The task runs on the IO thread.

• If TaskTraits don't contain BrowserThread::UI/IO:

  • If the task is posted through a SingleThreadTaskRunner obtained from CreateSingleThreadTaskRunnerWithTraits(..., mode):

    • Where mode is SingleThreadTaskRunnerThreadMode::DEDICATED: * The task runs on a thread that only runs tasks from that SingleThreadTaskRunner. This is not the main thread nor the IO thread.

    • Where mode is SingleThreadTaskRunnerThreadMode::SHARED: * The task runs on a thread that runs tasks from one or many unrelated SingleThreadTaskRunners. This is not the main thread nor the IO thread.

  • Otherwise:

    • The task runs in a thread pool.

As explained in Prefer Sequences to Threads, tasks should generally run on a sequence in a thread pool rather than on a dedicated thread.

Making blocking calls (which do not use the CPU)

How to make a blocking call without preventing other tasks from being scheduled?

The steps depend on where the task runs (see Where will a task run?).

If the task runs in a thread pool:

• Annotate the scope that may block with ScopedBlockingCall(BlockingType::MAY_BLOCK/WILL_BLOCK). A few milliseconds after the annotated scope is entered, the capacity of the thread pool is incremented. This ensures that your task doesn't reduce the number of tasks that can run concurrently on the CPU. If the scope exits, the thread pool capacity goes back to normal.

If the task runs on the main thread, the IO thread or a SHARED SingleThreadTaskRunner:

• Blocking on one of these threads will cause breakages. Move your task to a thread pool (or to a DEDICATED SingleThreadTaskRunner if necessary - see Prefer Sequences to Threads).

If the task runs on a DEDICATED SingleThreadTaskRunner:

• Annotate the scope that may block with ScopedBlockingCall(BlockingType::MAY_BLOCK/WILL_BLOCK). The annotation is a no-op that documents the blocking behavior (and makes it pass assertions). Tasks posted to the same DEDICATED SingleThreadTaskRunner won't run until your blocking task returns (they will never run if the blocking task never returns).

base/threading/scoped_blocking_call.h explains the difference between MAY_BLOCK and WILL_BLOCK and gives examples of blocking operations.

How to make a blocking call that may never return without preventing other tasks from being scheduled?

If you can't avoid making a call to a third-party library that may block off- CPU, follow recommendations in How to make a blocking call without affecting other tasks?. This ensures that a current task doesn't prevent other tasks from running even if it never returns.

Since tasks posted to the same sequence can't run concurrently, it is advisable to run tasks that may block indefinitely in parallel rather than in sequence (unless posting many such tasks at which point sequencing can be a useful tool to prevent flooding).

Do calls to blocking //base APIs need to be annotated with ScopedBlockingCall?

No. All blocking //base APIs (e.g. base::ReadFileToString, base::File::Read, base::SysInfo::AmountOfFreeDiskSpace, base::WaitableEvent::Wait, etc.) have their own internal annotations. See base/threading/scoped_blocking_call.h.

Can multiple ScopedBlockingCall be nested for the purpose of documentation?

Nested ScopedBlockingCall are supported. Most of the time, the inner ScopedBlockingCalls will no-op (the exception is WILL_BLOCK nested in MAY_BLOCK). As such, it is permitted to add a ScopedBlockingCall in the scope where a function that is already annotated is called for documentation purposes.:

Data GetDataFromNetwork() {
  ScopedBlockingCall scoped_blocking_call(BlockingType::MAY_BLOCK);
  // Fetch data from network.
  ...
  return data;
}

void ProcessDataFromNetwork() {
  Data data;
  {
    // Document the blocking behavior with a ScopedBlockingCall.
    // Permitted, but not required since GetDataFromNetwork() is itself annotated.
    ScopedBlockingCall scoped_blocking_call(BlockingType::MAY_BLOCK);
    data = GetDataFromNetwork();
  }
  CPUIntensiveProcessing(data);
}

However, CPU usage should always be minimal within the scope of ScopedBlockingCall. See base/threading/scoped_blocking_call.h.

Sequences

How to migrate from SingleThreadTaskRunner to SequencedTaskRunner?

The following mappings can be useful when migrating code from a SingleThreadTaskRunner to a SequencedTaskRunner:

• base::SingleThreadTaskRunner -> base::SequencedTaskRunner
  • SingleThreadTaskRunner::BelongsToCurrentThread() -> SequencedTaskRunner::RunsTasksInCurrentSequence()
• base::ThreadTaskRunnerHandle -> base::SequencedTaskRunnerHandle
• THREAD_CHECKER -> SEQUENCE_CHECKER
• base::ThreadLocalStorage::Slot -> base::SequenceLocalStorageSlot
• BrowserThread::DeleteOnThread -> base::OnTaskRunnerDeleter / base::RefCountedDeleteOnSequence
• BrowserMessageFilter::OverrideThreadForMessage() -> BrowserMessageFilter::OverrideTaskRunnerForMessage()
• CreateSingleThreadTaskRunnerWithTraits() -> CreateSequencedTaskRunnerWithTraits()
  • Every CreateSingleThreadTaskRunnerWithTraits() usage, outside of BrowserThread::UI/IO, should be accompanied with a comment and ideally a bug to make it sequence when the sequence-unfriendly dependency is addressed.

How to ensure mutual exclusion between tasks posted by a component?

Create a SequencedTaskRunner using CreateSequencedTaskRunnerWithTraits() and store it on an object that can be accessed from all the PostTask() call sites that require mutual exclusion. If there isn't a shared object that can own a common SequencedTaskRunner, use Lazy(Sequenced|SingleThread|COMSTA)TaskRunner in an anonymous namespace.

Tests

How to test code that posts tasks?

If the test uses BrowserThread::UI/IO, instantiate a content::TestBrowserThreadBundle for the scope of the test. Call TestBrowserThreadBundle::RunUntilIdle() to wait until all tasks have run.

If the test doesn't use BrowserThread::UI/IO, instantiate a base::test::ScopedTaskEnvironment for the scope of the test. Call base::test::ScopedTaskEnvironment::RunUntilIdle() to wait until all tasks have run.

In both cases, you can run tasks until a condition is met. A test that waits for a condition to be met is easier to understand and debug than a test that waits for all tasks to run.

int g_condition = false;

base::RunLoop run_loop;
base::PostTaskWithTraits(FROM_HERE, {}, base::BindOnce(
    [] (base::OnceClosure closure) {
        g_condition = true;
        std::move(quit_closure).Run();
    }, run_loop.QuitClosure()));

// Runs tasks until the quit closure is invoked.
run_loop.Run();

EXPECT_TRUE(g_condition);

Your question hasn't been answered?

1. Check the main Threading and Tasks docs.
2. Ping scheduler-dev@chromium.org.