Prefer ScopedNestableTaskAllower over manual save/restore

base/message_loop.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_MESSAGE_LOOP_H_
 #define BASE_MESSAGE_LOOP_H_
 #pragma once
 
 #include <queue>
 #include <string>
@@ skipping 49 matching lines @@
 //
 // NOTE: MessageLoop has task reentrancy protection.  This means that if a
 // task is being processed, a second task cannot start until the first task is
 // finished.  Reentrancy can happen when processing a task, and an inner
 // message pump is created.  That inner pump then processes native messages
 // which could implicitly start an inner task.  Inner message pumps are created
 // with dialogs (DialogBox), common dialogs (GetOpenFileName), OLE functions
 // (DoDragDrop), printer functions (StartDoc) and *many* others.
 //
 // Sample workaround when inner task processing is needed:
-//   bool old_state = MessageLoop::current()->NestableTasksAllowed();
-//   MessageLoop::current()->SetNestableTasksAllowed(true);
-//   HRESULT hr = DoDragDrop(...); // Implicitly runs a modal message loop here.
-//   MessageLoop::current()->SetNestableTasksAllowed(old_state);
-//   // Process hr  (the result returned by DoDragDrop().
+//   HRESULT hr;
+//   {
+//     MessageLoop::ScopedNestableTaskAllower allow(MessageLoop::current());
+//     hr = DoDragDrop(...); // Implicitly runs a modal message loop.
+//   }
+//   // Process |hr| (the result returned by DoDragDrop()).
 //
 // Please be SURE your task is reentrant (nestable) and all global variables
 // are stable and accessible before calling SetNestableTasksAllowed(true).
 //
 class BASE_EXPORT MessageLoop : public base::MessagePump::Delegate {
  public:
 #if defined(OS_WIN)
   typedef base::MessagePumpWin::Dispatcher Dispatcher;
   typedef base::MessagePumpObserver Observer;
 #elif !defined(OS_MACOSX) && !defined(OS_ANDROID)
@@ skipping 172 matching lines @@
   // Gets the message loop proxy associated with this message loop.
   scoped_refptr<base::MessageLoopProxy> message_loop_proxy() {
     return message_loop_proxy_.get();
   }
 
   // Enables or disables the recursive task processing. This happens in the case
   // of recursive message loops. Some unwanted message loop may occurs when
   // using common controls or printer functions. By default, recursive task
   // processing is disabled.
   //
+  // Please utilize |ScopedNestableTaskAllower| instead of calling these methods
+  // directly.  In general nestable message loops are to be avoided.  They are
+  // dangerous and difficult to get right, so please use with extreme caution.
+  //
   // The specific case where tasks get queued is:
   // - The thread is running a message loop.
   // - It receives a task #1 and execute it.
   // - The task #1 implicitly start a message loop, like a MessageBox in the
   //   unit test. This can also be StartDoc or GetSaveFileName.
   // - The thread receives a task #2 before or while in this second message
   //   loop.
   // - With NestableTasksAllowed set to true, the task #2 will run right away.
   //   Otherwise, it will get executed right after task #1 completes at "thread
   //   message loop level".
@@ skipping 382 matching lines @@
 #endif  // defined(OS_POSIX)
 };
 
 // Do not add any member variables to MessageLoopForIO!  This is important b/c
 // MessageLoopForIO is often allocated via MessageLoop(TYPE_IO).  Any extra
 // data that you need should be stored on the MessageLoop's pump_ instance.
 COMPILE_ASSERT(sizeof(MessageLoop) == sizeof(MessageLoopForIO),
                MessageLoopForIO_should_not_have_extra_member_variables);
 
 #endif  // BASE_MESSAGE_LOOP_H_