diff options
Diffstat (limited to 'chromium/base/run_loop.h')
| -rw-r--r-- | chromium/base/run_loop.h | 43 |
1 files changed, 21 insertions, 22 deletions
diff --git a/chromium/base/run_loop.h b/chromium/base/run_loop.h index b8ee4375c08..c2c39e3f3aa 100644 --- a/chromium/base/run_loop.h +++ b/chromium/base/run_loop.h @@ -44,7 +44,7 @@ class SingleThreadTaskRunner; // member and static methods unless explicitly indicated otherwise (e.g. // IsRunning/IsNestedOnCurrentThread()). RunLoop::Run can only be called once // per RunLoop lifetime. Create a RunLoop on the stack and call Run/Quit to run -// a nested RunLoop but please do not use nested loops in production code! +// a nested RunLoop but please avoid nested loops in production code! class BASE_EXPORT RunLoop { public: // The type of RunLoop: a kDefault RunLoop at the top-level (non-nested) will @@ -77,9 +77,8 @@ class BASE_EXPORT RunLoop { RunLoop(Type type = Type::kDefault); ~RunLoop(); - // Run the current RunLoop::Delegate. This blocks until Quit is called. Before - // calling Run, be sure to grab the QuitClosure in order to stop the - // RunLoop::Delegate asynchronously. + // Run the current RunLoop::Delegate. This blocks until Quit is called + // (directly or by running the RunLoop::QuitClosure). void Run(); // Run the current RunLoop::Delegate until it doesn't find any tasks or @@ -99,31 +98,30 @@ class BASE_EXPORT RunLoop { return running_; } - // Quit() quits an earlier call to Run() immediately. QuitWhenIdle() quits an - // earlier call to Run() when there aren't any tasks or messages in the queue. + // Quit() transitions this RunLoop to a state where no more tasks will be + // allowed to run at the run-loop-level of this RunLoop. If invoked from the + // owning thread, the effect is immediate; otherwise it is thread-safe but + // asynchronous. When the transition takes effect, the underlying message loop + // quits this run-loop-level if it is topmost (otherwise the desire to quit + // this level is saved until run-levels nested above it are quit). // - // These methods are thread-safe but note that Quit() is asynchronous when - // called from another thread (will quit soon but tasks that were already - // queued on this RunLoop will get to run first). + // QuitWhenIdle() results in this RunLoop returning true from + // ShouldQuitWhenIdle() at this run-level (the delegate decides when "idle" is + // reached). This is also thread-safe. // - // There can be other nested RunLoops servicing the same task queue. Quitting - // one RunLoop has no bearing on the others. Quit() and QuitWhenIdle() can be - // called before, during or after Run(). If called before Run(), Run() will - // return immediately when called. Calling Quit() or QuitWhenIdle() after the - // RunLoop has already finished running has no effect. - // - // WARNING: You must NEVER assume that a call to Quit() or QuitWhenIdle() will - // terminate the targeted message loop. If a nested RunLoop continues - // running, the target may NEVER terminate. It is very easy to livelock (run - // forever) in such a case. + // There can be other nested RunLoops servicing the same task queue. As + // mentioned above, quitting one RunLoop has no bearing on the others. Hence, + // you may never assume that a call to Quit() will terminate the underlying + // message loop. If a nested RunLoop continues running, the target may NEVER + // terminate. void Quit(); void QuitWhenIdle(); // Returns a RepeatingClosure that safely calls Quit() or QuitWhenIdle() (has // no effect if the RunLoop instance is gone). // - // These methods must be called from the thread on which the RunLoop was - // created. + // The closures must be obtained from the thread owning the RunLoop but may + // then be invoked from any thread. // // Returned closures may be safely: // * Passed to other threads. @@ -284,7 +282,8 @@ class BASE_EXPORT RunLoop { }; private: - FRIEND_TEST_ALL_PREFIXES(MessageLoopTypedTest, RunLoopQuitOrderAfter); + FRIEND_TEST_ALL_PREFIXES(SingleThreadTaskExecutorTypedTest, + RunLoopQuitOrderAfter); #if defined(OS_ANDROID) // Android doesn't support the blocking RunLoop::Run, so it calls |