dbus: Add comments about the right way to expose methods

dbus/exported_object.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 DBUS_EXPORTED_OBJECT_H_
 #define DBUS_EXPORTED_OBJECT_H_
 
 #include <dbus/dbus.h>
 
 #include <map>
@@ skipping 48 matching lines @@
       OnExportedCallback;
 
   // Exports the method specified by |interface_name| and |method_name|,
   // and blocks until exporting is done. Returns true on success.
   //
   // |method_call_callback| will be called in the origin thread, when the
   // exported method is called. As it's called in the origin thread,
   // |method_callback| can safely reference objects in the origin thread
   // (i.e. UI thread in most cases).
   //
+  // IMPORTANT NOTE: You should export all methods before requesting a
+  // service name by Bus::RequestOwnership/AndBlock(). If you do it in the
+  // wrong order (i.e. request a service name then export methods), there
+  // will be a short time period where your service is unable to respond to
+  // method calls because these methods aren't yet exposed. This race is a
+  // real problem as clients may start calling methods of your service as
+  // soon as you acquire a service name, by watching the name owner change.
+  //
   // BLOCKING CALL.
   virtual bool ExportMethodAndBlock(const std::string& interface_name,
                                     const std::string& method_name,
                                     MethodCallCallback method_call_callback);
 
   // Requests to export the method specified by |interface_name| and
   // |method_name|. See Also ExportMethodAndBlock().
   //
   // |on_exported_callback| is called when the method is exported or
   // failed to be exported, in the origin thread.
@@ skipping 84 matching lines @@
 
   // The method table where keys are absolute method names (i.e. interface
   // name + method name), and values are the corresponding callbacks.
   typedef std::map<std::string, MethodCallCallback> MethodTable;
   MethodTable method_table_;
 };
 
 }  // namespace dbus
 
 #endif  // DBUS_EXPORTED_OBJECT_H_