| # The Synchronous RunLoop Pattern | |
| The synchronous RunLoop pattern involves creating a new RunLoop, setting up a | |
| specified quit condition for it, then calling Run() on it to block the current | |
| thread until that quit condition is reached. | |
| ## Use this pattern when: | |
| You need to **block the current thread** until an event happens, and you have a | |
| way to get notified of that event, via a callback or observer interface or | |
| similar. A couple of common scenarios might be: | |
| * Waiting for an asynchronous event (like a network request) to complete | |
| * Waiting for an animation to finish | |
| * Waiting for a page to have loaded | |
| * Waiting for some call that requires a thread hop to complete | |
| The fact that this blocks a thread means it is **almost never appropriate | |
| outside test code**. | |
| ## Don't use this pattern when: | |
| * You don't really need the entire thread to wait | |
| * You don't have and can't add a way to get notified when the event happens | |
| * You're waiting for a timer to fire - for that, [TaskEnvironment] is likely a | |
| better fit. | |
| ## Alternatives / see also: | |
| * [TaskEnvironment] | |
| * Restructuring your code to not require blocking a thread | |
| ## How this pattern works: | |
| This pattern relies on two important facts about [base::RunLoop]: | |
| 1. `base::RunLoop::Quit()` is idempotent - once a RunLoop enters the quit | |
| state, quitting it again does nothing | |
| 2. Once a RunLoop is in the quit state, calling `base::RunLoop::Run()` on it is | |
| a no-op | |
| That means that if your code does this: | |
| ```c++ | |
| base::RunLoop loop; | |
| maybe-asynchronously { loop.Quit(); } | |
| loop.Run(); | |
| LOG(INFO) << "Hello!"; | |
| ``` | |
| then regardless of whether the maybe-asynchronous `loop.Quit()` is executed | |
| before or after `loop.Run()`, the "Hello!" message will never be printed before | |
| both `loop.Run()` and `loop.Quit()` have happened. If the `Quit` happens | |
| before the `Run`, the `Run` will be a no-op; if the `Quit` happens after the | |
| `Run` has started, the `Run` will exit after the `Quit`. | |
| ## How to use this pattern in Chromium: | |
| If the asynchronous thing in question takes a completion callback: | |
| ```c++ | |
| base::RunLoop run_loop; | |
| Reply reply; | |
| DoThingAndReply( | |
| base::BindLambdaForTesting([&](const Reply& r) { | |
| reply = r; | |
| run_loop.Quit(); | |
| })); | |
| run_loop.Run(); | |
| ``` | |
| or perhaps even just: | |
| ```c++ | |
| base::RunLoop run_loop; | |
| DoThing(run_loop.QuitClosure()); | |
| run_loop.Run(); | |
| ``` | |
| If there exists a GizmoObserver interface with an OnThingDone event: | |
| ```c++ | |
| class TestGizmoObserver : public GizmoObserver { | |
| public: | |
| TestGizmoObserver(base::RunLoop* loop, Gizmo* thing) | |
| : GizmoObserver(thing), loop_(loop) {} | |
| // GizmoObserver: | |
| void OnThingStarted(Gizmo* observed_gizmo) override { ... } | |
| void OnThingProgressed(Gizmo* observed_gizmo) override { ... } | |
| void OnThingDone(Gizmo* observed_gizmo) override { | |
| loop_->Quit(); | |
| } | |
| }; | |
| base::RunLoop run_loop; | |
| TestGizmoObserver observer(&run_loop, gizmo); | |
| gizmo->StartDoingThing(); | |
| run_loop.Run(); | |
| ``` | |
| This is sometimes wrapped up into a helper class that internally constructs the | |
| RunLoop like so, if all you need to do is wait for the event but don't care | |
| about observing any intermediate states too: | |
| ```c++ | |
| class ThingDoneWaiter : public GizmoObserver { | |
| public: | |
| ThingDoneWaiter(Gizmo* thing) : GizmoObserver(thing) {} | |
| void Wait() { | |
| run_loop_.Run(); | |
| } | |
| // GizmoObserver: | |
| void OnThingDone(Gizmo* observed_gizmo) { | |
| run_loop_.Quit(); | |
| } | |
| private: | |
| RunLoop run_loop_; | |
| }; | |
| ThingDoneWaiter waiter(gizmo); | |
| gizmo->StartDoingThing(); | |
| waiter.Wait(); | |
| ``` | |
| ## Events vs States | |
| It's important to differentiate between waiting on an *event* (such as a | |
| notification or callback being fired) vs waiting for a *state* (such as a | |
| property on a given object). | |
| When waiting for events, it is crucial that the observer is constructed in time | |
| to see the event (see also [waiting too late](#starting-to-wait-for-an-event-too-late)). | |
| States, on the other hand, can be queried beforehand in the body of a | |
| Wait()-style function. | |
| The following is an example of a Waiter helper class that waits for a state, as | |
| opposed to an event: | |
| ```c++ | |
| class GizmoReadyWaiter : public GizmoObserver { | |
| public: | |
| GizmoReadyObserver(Gizmo* gizmo) | |
| : gizmo_(gizmo) {} | |
| ~GizmoReadyObserver() override = default; | |
| void WaitForGizmoReady() { | |
| if (!gizmo_->ready()) { | |
| gizmo_observation_.Observe(gizmo_); | |
| run_loop_.Run(); | |
| } | |
| } | |
| // GizmoObserver: | |
| void OnGizmoReady(Gizmo* observed_gizmo) { | |
| run_loop_.Quit(); | |
| } | |
| private: | |
| RunLoop run_loop_; | |
| Gizmo* gizmo_; | |
| base::ScopedObservation<Gizmo, GizmoObserver> gizmo_observation_{this}; | |
| }; | |
| ``` | |
| ## Sharp edges | |
| ### Starting to wait for an event too late | |
| A common mis-use of this pattern is like so: | |
| ```c++ | |
| gizmo->StartDoingThing(); | |
| base::RunLoop run_loop; | |
| TestGizmoObserver observer(&run_loop, gizmo); | |
| run_loop.Run(); | |
| ``` | |
| This looks tempting because it seems that you can write a helper function: | |
| ```c++ | |
| void TerribleHorribleNoGoodVeryBadWaitForThing(Gizmo* gizmo) { | |
| base::RunLoop run_loop; | |
| TestGizmoObserver observer(&run_loop, gizmo); | |
| run_loop.Run(); | |
| } | |
| ``` | |
| and then your test code can simply read: | |
| ```c++ | |
| gizmo->StartDoingThing(); | |
| TerribleHorribleNoGoodVeryBadWaitForThing(gizmo); | |
| ``` | |
| However, this is a recipe for a flaky test: if `gizmo->StartDoingThing()` | |
| *completes* and would deliver the `OnThingDone` callback before your | |
| `TestGizmoObserver` is ever constructed, the `TestGizmoObserver` will never | |
| receive `OnThingDone`, and then your `run_loop.Run()` will run forever, | |
| frustrating a future tree sheriff (and then probably you, shortly afterward). | |
| This is especially dangerous when `gizmo->StartDoingThing()` involves a thread | |
| hop or network request, because these can unpredictably complete before or after | |
| your observer gets constructed. To be safe, always begin observing the event | |
| *before* running the code that will eventually cause the event! | |
| If you still really want a helper function, perhaps you just want to inline the | |
| start: | |
| ```c++ | |
| void NiceFriendlyDoThingAndWait(Gizmo* gizmo) { | |
| base::RunLoop run_loop; | |
| TestGizmoObserver observer(&run_loop, gizmo); | |
| gizmo->StartDoingThing(); | |
| run_loop.Run(); | |
| } | |
| ``` | |
| with the test code being: | |
| ```c++ | |
| NiceFriendlyDoThingAndWait(gizmo); | |
| ``` | |
| Note that this is not an issue when waiting on a *state*, since the observer can | |
| query to see if that state is already the current state. | |
| ### Guessing RunLoop cycles | |
| Sometimes, there's no easy way to observe completion of an event. In that case, | |
| if the code under test looks like this: | |
| ```c++ | |
| void StartDoingThing() { PostTask(&StepOne); } | |
| void StepOne() { PostTask(&StepTwo); } | |
| void StepTwo() { /* done! */ } | |
| ``` | |
| it can be tempting to do: | |
| ```c++ | |
| gizmo->StartDoingThing(); | |
| base::RunLoop().RunUntilIdle(); | |
| /* now it's done! */ | |
| ``` | |
| However, doing this is adding dependencies to your test code on the exact async | |
| behavior of the production code - for example, the production code may depend on | |
| work happening on another TaskRunner, which this won't successfully wait for. | |
| This will make your test brittle and flaky. | |
| Instead of doing this, it's vastly better to add a way (even if it's just via a | |
| [test API]) to observe the event you're interested in. | |
| ### Not managing lifetimes | |
| As with most patterns, lifetimes can be an issue with this pattern when using | |
| observers. If you are waiting on a given event to happen, and the object that's | |
| being observed instead goes out of scope, the test may hang. | |
| Similar badness can happen if the Waiter isn't properly removed as an observer, | |
| which could lead to Use-After-Frees. | |
| There are two good mitigation practices here. | |
| #### Keep Waiter-style helper classes as narrowly scoped as possible. | |
| Consider something like | |
| ```c++ | |
| TEST_F(GizmoTest, WaitForGizmo) { | |
| GizmoWaiter waiter; | |
| Gizmo gizmo; | |
| gizmo.Initialize(); | |
| waiter.WaitForGizmoReady(); | |
| ASSERT_TRUE(gizmo.ready()); | |
| } | |
| ``` | |
| This looks safe, but may not be. If GizmoObserver removes itself as an observer | |
| from Gizmo in its destructor, this will result in a Use-After-Free during the | |
| test tear down. Instead, scope the GizmoWaiter more narrowly: | |
| ```c++ | |
| TEST_F(GizmoTest, WaitForGizmo) { | |
| Gizmo gizmo; | |
| { | |
| GizmoWaiter waiter; | |
| gizmo.Initialize(); | |
| waiter.WaitForGizmoReady(); | |
| } | |
| ASSERT_TRUE(gizmo.ready()); | |
| } | |
| ``` | |
| Since the GizmoWaiter is now narrowly-scoped, it will be destroyed when it is | |
| no longer needed, and avoid Use-After-Free concerns. | |
| #### If in doubt, handle the destruction case appropriately | |
| If you need to potentially handle the case where the object being observed is | |
| destroyed while a waiter is still active, you can handle the destruction case | |
| gracefully. | |
| ```c++ | |
| class GizmoReadyWaiter : public GizmoObserver { | |
| public: | |
| GizmoReadyObserver(Gizmo* gizmo) | |
| : gizmo_(gizmo) {} | |
| ~GizmoReadyObserver() override = default; | |
| void WaitForGizmoReady() { | |
| ASSERT_TRUE(gizmo_) | |
| << "Trying to call Wait() after the Gizmo was destroyed!"; | |
| if (!gizmo_->ready()) { | |
| gizmo_observation_.Observe(gizmo_); | |
| run_loop_.Run(); | |
| } | |
| } | |
| // GizmoObserver: | |
| void OnGizmoReady(Gizmo* observed_gizmo) { | |
| gizmo_observation_.Reset(); | |
| run_loop_.Quit(); | |
| } | |
| void OnGizmoDestroying(Gizmo* observed_gizmo) { | |
| DCHECK_EQ(gizmo_, observed_gizmo); | |
| gizmo_ = nullptr; | |
| // Remove the observer now, to avoid a UAF in the destructor. | |
| gizmo_observation_.Reset(); | |
| // Bail out so we don't time out in the test waiting for a ready state | |
| // that will never come. | |
| run_loop_.Quit(); | |
| // Was this a possible expected outcome? If not, consider: | |
| // ADD_FAILURE() << "The Gizmo was destroyed before it was ready!"; | |
| } | |
| private: | |
| RunLoop run_loop_; | |
| Gizmo* gizmo_; | |
| base::ScopedObservation<Gizmo, GizmoObserver> gizmo_observation_{this}; | |
| }; | |
| ``` | |
| [base::RunLoop]: ../../base/run_loop.h | |
| [TaskEnvironment]: ../threading_and_tasks_testing.md | |
| [test API]: testapi.md |