Add Bus::ShutdownOnDBusThreadAndBlock() and remove bus::Shutdown()

dbus/bus.h

 // Copyright (c) 2011 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 DBUS_BUS_H_
 #define DBUS_BUS_H_
 #pragma once
 
 #include <map>
 #include <set>
 #include <string>
 #include <dbus/dbus.h>
 
 #include "base/callback.h"
 #include "base/memory/ref_counted.h"
 #include "base/memory/scoped_ptr.h"
+#include "base/synchronization/waitable_event.h"
 #include "base/threading/platform_thread.h"
 #include "base/tracked_objects.h"
 
 class MessageLoop;
 
 namespace base {
 class Thread;
 }
 
 namespace dbus {
@@ skipping 27 matching lines @@
 // supplied). AssertOnDBusThread() is placed in these functions.
 //
 // Note that it's hard to tell if a libdbus function is actually blocking
 // or not (ex. dbus_bus_request_name() internally calls
 // dbus_connection_send_with_reply_and_block(), which is a blocking
 // call). To err on the safe side, we consider all libdbus functions that
 // deal with the connection to dbus-daemon to be blocking.
 //
 // SHUTDOWN
 //
-// The Bus object must be shut down manually by Shutdown() or
-// ShutdownAndBlock(). We require the manual shutdown as we should not
-// issue blocking calls in the destructor.
+// The Bus object must be shut down manually by ShutdownAndBlock() and
+// friends. We require the manual shutdown to make the operation explicit
+// rather than doing it silently in the destructor.
 //
 // EXAMPLE USAGE:
 //
 // Synchronous method call:
 //
 //   dbus::Bus::Options options;
 //   // Set up the bus options here.
 //   ...
 //   dbus::Bus bus(options);
 //
@@ skipping 35 matching lines @@
 //   ...
 //   dbus::ExportedObject* exported_object =
 //       bus.GetExportedObject(service_name, object_path);
 //   exported_object.ExportMethod(interface_name, method_name,
 //                                base::Bind(&Echo),
 //                                base::Bind(&OnExported));
 //
 // WHY IS THIS A REF COUNTED OBJECT?
 //
 // Bus is a ref counted object, to ensure that |this| of the object is
-// alive when callbacks referencing |this| are called. However, after
-// Shutdown() is called, |connection_| can be NULL. Hence, callbacks should
+// alive when callbacks referencing |this| are called. However, after the
+// bus is shut down, |connection_| can be NULL. Hence, callbacks should
 // not rely on that |connection_| is alive.
 class Bus : public base::RefCountedThreadSafe<Bus> {
  public:
   // Specifies the bus type. SESSION is used to communicate with per-user
   // services like GNOME applications. SYSTEM is used to communicate with
   // system-wide services like NetworkManager.
   enum BusType {
     SESSION = DBUS_BUS_SESSION,
     SYSTEM  = DBUS_BUS_SYSTEM,
   };
@@ skipping 22 matching lines @@
     // If the thread is set, the bus object will use the message loop
     // attached to the thread to process asynchronous operations.
     //
     // The thread should meet the following requirements:
     // 1) Already running.
     // 2) Has a MessageLoopForIO.
     // 3) Outlives the bus.
     base::Thread* dbus_thread;  // NULL by default.
   };
 
-  // Called when shutdown is done. Used for Shutdown().
-  typedef base::Callback<void ()> OnShutdownCallback;
-
   // Creates a Bus object. The actual connection will be established when
   // Connect() is called.
   explicit Bus(const Options& options);
 
   // Gets the object proxy for the given service name and the object path.
   // The caller must not delete the returned object.
   //
   // Returns an existing object proxy if the bus object already owns the
   // object proxy for the given service name and the object path.
   // Never returns NULL.
@@ skipping 33 matching lines @@
   // Shuts down the bus and blocks until it's done. More specifically, this
   // function does the following:
   //
   // - Unregisters the object paths
   // - Releases the service names
   // - Closes the connection to dbus-daemon.
   //
   // BLOCKING CALL.
   virtual void ShutdownAndBlock();
 
-  // Shuts down the bus in the D-Bus thread. |callback| will be called in
-  // the origin thread.
+  // Similar to ShutdownAndBlock(), but this function is used to
+  // synchronously shut down the bus that uses the D-Bus thread. This
+  // function is intended to be used at the very end of the browser
+  // shutdown, where it makes more sense to shut down the bus
+  // synchronously, than trying to make it asynchronous.
   //
-  // Must be called in the origin thread.
-  virtual void Shutdown(OnShutdownCallback callback);
+  // BLOCKING CALL, but must be called in the origin thread.
+  virtual void ShutdownOnDBusThreadAndBlock();
+
+  // Returns true if the shutdown has been completed.
+  bool shutdown_completed() { return shutdown_completed_; }
 
   //
   // The public functions below are not intended to be used in client
   // code. These are used to implement ObjectProxy and ExportedObject.
   //
 
   // Connects the bus to the dbus-daemon.
   // Returns true on success, or the bus is already connected.
   //
   // BLOCKING CALL.
@@ skipping 137 matching lines @@
   // AssertOnOriginThread().
   virtual void AssertOnDBusThread();
 
  protected:
   // This is protected, so we can define sub classes.
   virtual ~Bus();
 
  private:
   friend class base::RefCountedThreadSafe<Bus>;
 
-  // Helper function used for Shutdown().
-  void ShutdownInternal(OnShutdownCallback callback);
+  // Helper function used for ShutdownOnDBusThreadAndBlock().
+  void ShutdownOnDBusThreadAndBlockInternal();
 
   // Processes the all incoming data to the connection, if any.
   //
   // BLOCKING CALL.
   void ProcessAllIncomingDataIfAny();
 
   // Called when a watch object is added. Used to start monitoring the
   // file descriptor used for D-Bus communication.
   dbus_bool_t OnAddWatch(DBusWatch* raw_watch);
 
@@ skipping 24 matching lines @@
   static void OnToggleWatchThunk(DBusWatch* raw_watch, void* data);
   static dbus_bool_t OnAddTimeoutThunk(DBusTimeout* raw_timeout, void* data);
   static void OnRemoveTimeoutThunk(DBusTimeout* raw_timeout, void* data);
   static void OnToggleTimeoutThunk(DBusTimeout* raw_timeout, void* data);
   static void OnDispatchStatusChangedThunk(DBusConnection* connection,
                                            DBusDispatchStatus status,
                                            void* data);
   const BusType bus_type_;
   const ConnectionType connection_type_;
   base::Thread* dbus_thread_;
+  base::WaitableEvent on_shutdown_;
   DBusConnection* connection_;
 
   MessageLoop* origin_loop_;
   base::PlatformThreadId origin_thread_id_;
   base::PlatformThreadId dbus_thread_id_;
 
   std::set<std::string> owned_service_names_;
   // The following sets are used to check if rules/object_paths/filters
   // are properly cleaned up before destruction of the bus object.
   std::set<std::string> match_rules_added_;
   std::set<std::string> registered_object_paths_;
   std::set<DBusHandleMessageFunction> filter_functions_added_;
 
   // ObjectProxyTable is used to hold the object proxies created by the
   // bus object. Key is a concatenated string of service name + object path,
   // like "org.chromium.TestService/org/chromium/TestObject".
   typedef std::map<std::string,
                    scoped_refptr<dbus::ObjectProxy> > ObjectProxyTable;
   ObjectProxyTable object_proxy_table_;
 
   // ExportedObjectTable is used to hold the exported objects created by
   // the bus object. Key is a concatenated string of service name +
   // object path, like "org.chromium.TestService/org/chromium/TestObject".
   typedef std::map<std::string,
                    scoped_refptr<dbus::ExportedObject> > ExportedObjectTable;
   ExportedObjectTable exported_object_table_;
 
   bool async_operations_set_up_;
+  bool shutdown_completed_;
 
   // Counters to make sure that OnAddWatch()/OnRemoveWatch() and
   // OnAddTimeout()/OnRemoveTimeou() are balanced.
   int num_pending_watches_;
   int num_pending_timeouts_;
 
   DISALLOW_COPY_AND_ASSIGN(Bus);
 };
 
 }  // namespace dbus
 
 #endif  // DBUS_BUS_H_