Google celebrates Women's History Month. See how.

Threading tips in tests

Quite a few asynchronous types used in driver writing are thread-unsafe and they check that they are always used from their associated synchronized dispatcher, to ensure memory safety, for example:

  • {fdf,component}::OutgoingDirectory
  • {fdf,fidl}::Client, {fdf,fidl}::WireClient
  • {fdf,fidl}::ServerBinding, {fdf,fidl}::ServerBindingGroup

If you are testing driver async objects containing these types, using them from the wrong execution context will lead to a crash, where the stack trace involves "synchronization_checker". This is a safety feature to prevent silent data corruption. Here are some tips to avoid the crashes.

Write single-threaded tests

The most straightforward approach is to execute the test assertions and use those objects from the same thread, typically the main thread:

Example involving async::Loop:

TEST(MyRegister, Read) {
  async::Loop loop{&kAsyncLoopConfigAttachToCurrentThread};
  // For illustration purposes, this is the thread-unsafe type being tested.
  MyRegister reg{loop.dispatcher()};
  // Use the object on the current thread.
  // Run any async work scheduled by the object, also on the current thread.
  // Read from the object on the current thread.
  EXPECT_EQ(obj.GetValue(), 123);

Example involving fdf::TestSynchronizedDispatcher on the main thread:

TEST(MyRegister, Read) {
  fdf::TestSynchronizedDispatcher test_driver_dispatcher_{
  // For illustration purposes, this is the thread-unsafe type being tested.
  MyRegister reg{dispatcher.dispatcher()};
  // Use the object on the current thread.
  // Run any async work scheduled by the object, also on the current thread.
  // Read from the object on the current thread.
  EXPECT_EQ(obj.GetValue(), 123);

Note that fdf::TestSynchronizedDispatcher may also be driven by driver runtime managed thread pool if a driver needs to make synchronous calls. Objects associated with driver dispatchers backed by the thread pool should not be accessed from the main thread. As a simple rule, if the associated dispatcher is not started with kDispatcherDefault, then it may not be running on the main thread.

When using the async objects from a single thread, their contained async::synchronization_checker will not panic.

Call blocking functions

The single-threaded way breaks down if you need to call a blocking function which blocks on the dispatcher processing some messages. If you first call the blocking function and then run the loop, that will deadlock because the loop will not be run until the blocking function returns, and the blocking function will not return unless the loop is run.

To call blocking functions, you need a way to run that function and run the loop on different threads. In addition, the blocking function should not directly access the object associated with the dispatcher without synchronization, because that may race with the loop thread.

To address both concerns, you can wrap the thread-unsafe async object in a async_patterns::TestDispatcherBound, which ensures that all accesses to the wrapped object happen on its associated dispatcher.

Example involving async::Loop, reusing the MyRegister type from earlier:

// Let's say this function blocks and then returns some value we need.
int GetValueInABlockingWay();

TEST(MyRegister, Read) {
  // Configure the loop to register itself as the dispatcher for the
  // loop thread, such that the |MyRegister| constructor may use
  // `async_get_default_dispatcher()` to obtain the loop dispatcher.
  async::Loop loop{&kAsyncLoopConfigNoAttachToCurrentThread};

  // Construct the |MyRegister| on the loop thread.
  async_patterns::TestDispatcherBound<MyRegister> reg{
      loop.dispatcher(), std::in_place};

  // Schedule a |SetValue| call on the loop thread and wait for it.
  reg.SyncCall(&MyRegister::SetValue, 123);

  // Call the blocking function on the main thread.
  // This will not deadlock, because we have started a loop thread
  // earlier to process messages for the |MyRegister| object.
  int value = GetValueInABlockingWay();
  EXPECT_EQ(value, 123);

  // |GetValue| returns a value; |SyncCall| will proxy that back.
  EXPECT_EQ(reg.SyncCall(&MyRegister::GetValue), 123);

In this example, access to the MyRegister object happens on its corresponding async::Loop thread. This in turn frees the main thread to make blocking calls. When the main thread would like to interact with MyRegister, it needs to do so indirectly using SyncCall.

Another common pattern in tests is to set up FIDL servers on a separate thread with TestDispatcherBound and have the test fixture class used on the main test thread. The TestDispatcherBound objects will become members of the test fixture class.

Example involving fdf::TestSynchronizedDispatcher:

In drivers, often the blocking work itself happens inside a driver. For example, the blocking work may involve a synchronous FIDL call made by the driver, over a FIDL protocol that is faked out during testing. In the following example, the BlockingIO class represents the driver, and the FakeRegister class represents a fake implementation of some FIDL protocol used by BlockingIO. When FakeRegister does not speak FIDL over driver transports, an async::Loop is a good way to isolate it to separate thread such that we can make the blocking call from the main thread.

// Here is the bare skeleton of a driver object that makes a synchronous call.
class BlockingIO {
  // Let's say this function blocks to update the value stored in a
  // |FakeRegister|.
  void SetValueInABlockingWay(int value);

  /* Other details omitted */

TEST(BlockingIO, Read) {
  // Configure the loop to register itself as the dispatcher for the
  // loop thread, such that the |FakeRegister| constructor may use
  // `async_get_default_dispatcher()` to obtain the loop dispatcher.
  async::Loop register_loop{&kAsyncLoopConfigNoAttachToCurrentThread};

  // Construct the |FakeRegister| on the loop thread.
  async_patterns::TestDispatcherBound<FakeRegister> reg{
      register_loop.dispatcher(), std::in_place};

  // Start a driver dispatcher for |BlockingIO| and register it as the
  // dispatcher for the main thread.
  fdf::TestSynchronizedDispatcher driver_dispatcher{fdf::kDispatcherDefault};

  // Construct the |BlockingIO| on the main thread.
  BlockingIO io{driver_dispatcher.dispatcher()};

  // Call the blocking function. The |register_loop| will respond to it in the
  // background.

  // Check the value from the fake.
  // |GetValue| returns an |int|; |AsyncCall| will proxy that back.
  EXPECT_EQ(fdf::WaitFor(reg.AsyncCall(&FakeRegister::GetValue).ToFuture()), 123);

When the dispatcher of the driver object is backed by the main thread, there is no need to go through a TestDispatcherBound. We can safely use the BlockingIO driver object, including making the SetValueInABlockingWay call, from the main thread.

When the FakeRegister fake object lives on the register_loop thread, we need to use a TestDispatcherBound to safely interact with it from the main thread. Instead of SyncCall which blocks without doing anything else, here we find the fdf::WaitFor(object.AsyncCall(&SomeMethod).ToFuture()) pattern. fdf::WaitFor can wait on a std::future while concurrently running driver dispatchers backed by the main thread. Running those dispatchers will be necessary if SomeMethod involves talking to an async object associated with one of those dispatchers. In some driver dispatcher configurations, all dispatchers will be backed by threads from a managed thread pool, in which case you can use SyncCall while the thread pool works in the background. The AsyncCall and fdf::WaitFor combination still works in those configurations, so you may default to that if in doubt.

Blocking on the future directly, i.e. object.AsyncCall(&SomeMethod).ToFuture().get(), is equivalent to SyncCall.

Granularity of DispatcherBound objects

The following guide applies to both TestDispatcherBound and its production counterpart, DispatcherBound.

When serializing access to an object to occur over a specific synchronized dispatcher, it's important to consider which other objects need to be used from that same dispatcher. It can be more effective to combine both objects inside the same DispatcherBound.

For instance, if you're using a component::OutgoingDirectory, which synchronously calls into FIDL server implementations like adding a binding to a fidl::ServerBindingGroup, you must ensure that both objects are on the same dispatcher.

If you only put the OutgoingDirectory inside a [Test]DispatcherBound to work around its synchronization checker, but leave the ServerBindingGroup somewhere else e.g. on the main thread, you'll get a crash when the OutgoingDirectory object calls into the ServerBindingGroup from the dispatcher thread, tripping the checker in ServerBindingGroup.

To solve this problem, you can place the OutgoingDirectory and the objects it references, such as the ServerBindingGroup or any server state, inside a bigger object, and then put that object in a DispatcherBound. This way, both the OutgoingDirectory and the ServerBindingGroup will be used from the same synchronized dispatcher, and you won't experience any crashes. You can see an example test that uses this technique.

In general, it's helpful to divide your classes along concurrency boundaries. By doing so, you'll ensure that all the objects that need to be used on the same dispatcher are synchronized, preventing potential crashes or data races.

See also