Service Manager: Rework Service and ServiceContext lifetime

services/service_manager/public/cpp/service_context.h

Index: services/service_manager/public/cpp/service_context.h
diff --git a/services/service_manager/public/cpp/service_context.h b/services/service_manager/public/cpp/service_context.h
index 38b08399d9c02b38f1f9e1592f5d0b312014dfc9..f560ad5e21a1e61dd5956d743e6bb1599f2e0a0d 100644
--- a/services/service_manager/public/cpp/service_context.h
+++ b/services/service_manager/public/cpp/service_context.h
@@ -28,27 +28,29 @@ namespace service_manager {
 //   Service Manager to inform this service of lifecycle events and
 //   inbound connections brokered by it.
 //
-// This class should be used in two scenarios:
-// - During early startup to bind the mojom::ServiceRequest obtained from
-//   the Service Manager, typically in response to either ServiceMain() or
-//   main().
-// - In an implementation of mojom::ServiceFactory to bind the
-//   mojom::ServiceRequest passed via CreateService. In this scenario there can
-//   be many instances of this class per process.
-//
-// Instances of this class are constructed with an implementation of the Service
-// Manager Client Lib's Service interface. See documentation in service.h
-// for details.
+// This class owns an instance of a Service implementation, and there should be
+// exactly one instance of this class for every logical service instance running
+// in the system.
 //
+// This class is generally used to handle incoming mojom::ServiceRequests from
+// the Service Manager. These can either come from ServiceRunner, from the
+// command-line (in the form of a pipe token), from a mojom::ServiceFactory
+// call, or from some other embedded service-running facility defined by the
+// client.
 class ServiceContext : public mojom::Service {
  public:
   // Creates a new ServiceContext bound to |request|. This connection may be
-  // used immediately to make outgoing connections via connector().  Does not
-  // take ownership of |service|, which must remain valid for the lifetime of
-  // ServiceContext. If either |connector| or |connector_request| is non-null
-  // both must be non-null. If both are null, the connection will create its own
+  // used immediately to make outgoing connections via connector().
+  //
+  // This ServiceContext routes all incoming mojom::Service messages and
+  // error signals to |service|, which it owns.
+  //
+  // If either |connector| or |connector_request| is non-null both must be
+  // non-null. If both are null, the context will create its own
   // Connector and request to pass to the Service Manager on initialization.
-  ServiceContext(service_manager::Service* service,
+  //
+  // TODO(rockot): Clean up the connector/connector_request junk.
+  ServiceContext(std::unique_ptr<service_manager::Service> service,
                  mojom::ServiceRequest request,
                  std::unique_ptr<Connector> connector = nullptr,
                  mojom::ConnectorRequest connector_request = nullptr);
@@ -56,14 +58,49 @@ class ServiceContext : public mojom::Service {
   ~ServiceContext() override;
 
   Connector* connector() { return connector_.get(); }
-  const Identity& identity() { return local_info_.identity; }
+  const ServiceInfo& local_info() const { return local_info_; }
+  const Identity& identity() const { return local_info_.identity; }
 
   // Specify a function to be called when the connection to the service manager
-  // is lost.
-  // Note that if connection has already been lost, then |closure| is called
-  // immediately.
+  // is lost. Note that if connection has already been lost, then |closure| is
+  // called immediately.
+  //
+  // It is acceptable for |closure| to delete this ServiceContext.
   void SetConnectionLostClosure(const base::Closure& closure);
 
+  // Informs the Service Manager that this instance is ready to terminate. If
+  // the Service Manager has any outstanding connection requests for this
+  // instance, the request is ignored; the instance will eventually receive
+  // the pending request(s) and can then appropriately decide whether or not
+  // it still wants to quit.
+  //
+  // If the request is granted, the Service Manager will service the connection
+  // to this ServiceContext and Service::OnStop() will eventually be invoked.
+  void RequestQuit();
+
+  // Immediately severs the connection to the Service Manager.
+  //
+  // Note that calling this before the Service receives OnStop() can lead to
+  // unpredictable behavior, specifically because clients may have inbound
+  // connections in transit which may have already been brokered by the Service
+  // Manager and thus will be irreparably broken on the client side.
+  //
+  // Use of this call before OnStop() should be reserved for exceptional cases.
+  void DisconnectFromServiceManager();
+
+  // Immediately severs the connection to the Service Manager.
+  //
+  // If a connection-lost closure was set, it is immediately invoked. Note that
+  // it is never necessary or meaningful to call this after the Service
+  // has received OnStop().
+  //
+  // See comments on DisconnectFromServiceManager() regarding abrupt
+  // disconnection from the Service Manager.
+  void QuitNow();
+
+  // Simliar to QuitNow() above but also destroys the Service instance.
+  void DestroyService();
+
  private:
   using InterfaceRegistryMap =
       std::map<InterfaceRegistry*, std::unique_ptr<InterfaceRegistry>>;
@@ -78,9 +115,6 @@ class ServiceContext : public mojom::Service {
   void OnRegistryConnectionError(InterfaceRegistry* registry);
   void DestroyConnectionInterfaceRegistry(InterfaceRegistry* registry);
 
-  // A callback called when OnStart() is run.
-  base::Closure initialize_handler_;
-
   // We track the lifetime of incoming connection registries as a convenience
   // for the client.
   InterfaceRegistryMap connection_interface_registries_;
@@ -89,11 +123,12 @@ class ServiceContext : public mojom::Service {
   // Manager.
   mojom::ConnectorRequest pending_connector_request_;
 
-  service_manager::Service* service_;
+  std::unique_ptr<service_manager::Service> service_;
   mojo::Binding<mojom::Service> binding_;
   std::unique_ptr<Connector> connector_;
   service_manager::ServiceInfo local_info_;
-  bool should_run_connection_lost_closure_ = false;
+
+  bool service_quit_ = false;
 
   base::Closure connection_lost_closure_;