Rename shell namespace to service_manager

services/service_manager/README.md

 # Service Manager User Guide
 
 ## What is the Service Manager?
 
 The Service Manager is a tool that brokers connections and capabilities between
 and manages instances of components, referred to henceforth as “services”.
 
 The Service Manager performs the following functions:
 
 * Brokering connections between services, including communicating policies such
@@ skipping 43 matching lines @@
 has its own unique Identity. From the Service Manager’s perspective, a service’s
 Identity is represented by the tuple of the its Name, UserId and Instance Name.
 The Name is a formatted string that superficially represents a scheme:host pair,
 but actually isn’t a URL. More on the structure of these names later. The UserId
 is a string GUID, representing the user the service is run as. The Instance Name
 is a string, typically (but not necessarily) derived from the Name, which can be
 used to allow multiple instances of a service to exist for the same Name,UserId
 pair. In Chrome an example of this would be multiple instances of the renderer
 or the same profile.
 
-A Service implements the Mojo interface shell.mojom.Service, which is the
+A Service implements the Mojo interface service_manager.mojom.Service, which is the
 primary means the Service Manager has of communicating with its service. Service
 has two methods: OnStart(), called once at when the Service Manager first learns
 about the service, and OnConnect(), which the Service Manager calls every time
 some other service tries to connect to this one.
 
 Services have a link back to the Service Manager too, primarily in the form of
-the shell.mojom.Connector interface. The Connector allows services to open
+the service_manager.mojom.Connector interface. The Connector allows services to open
 connections to other services.
 
 A unique connection from the Service Manager to a service is called an
 “instance,” each with its own unique identifier, called an instance id. Every
 instance has a unique Identity. It is possible to locate an existing instance
 purely using its Identity.
 
 Services define their own lifetimes. Services in processes started by other
 services (rather than the Service Manager) may even outlive the connection with
 the Service Manager. For processes launched by the Service Manager, when a
 service wishes to terminate it closes the Service pipe with the Service Manager
 and the Service Manager destroys its corresponding instance and asks the process
 to exit.
 
 #### A simple Service example
 
 Consider this simple application that implements the Service interface:
 
 **app.cc:**
 
     #include “"mojo/public/c/system/main.h”"
     #include “"services/service_manager/public/cpp/application_runner.h”"
     #include “"services/service_manager/public/cpp/connector.h”"
     #include “"services/service_manager/public/cpp/connection.h”"
     #include “"services/service_manager/public/cpp/identity.h”"
     #include “"services/service_manager/public/cpp/service.h”"
 
-    class Service : public shell::Service {
+    class Service : public service_manager::Service {
      public:
       Service() {}
       ~Service() override {}
 
-      // Overridden from shell::Service:
-      void OnStart(const shell::Identity& identity) override {
+      // Overridden from service_manager::Service:
+      void OnStart(const service_manager::Identity& identity) override {
       }
-      bool OnConnect(shell::Connection* connection) override {
+      bool OnConnect(service_manager::Connection* connection) override {
         return true;
       }
     };
 
     MojoResult ServiceMain(MojoHandle service_request_handle) {
-      return shell::ServiceRunner(new Service).Run(service_request_handle);
+      return service_manager::ServiceRunner(new Service).Run(service_request_handle);
     }
 
     app_manifest.json:
 
     {
       "“manifest_version"”: 1,
       "“name"”: "“mojo:app”",
       "“display_name"”: “"Example App”",
       "“capabilities"”: {}
     }
 
 **BUILD.gn:**
 
     import(“"//mojo/public/mojo_application.gni”")
 
     service(“"app"”) {
       sources = [ "“app.cc"” ]
-      deps = [ "“//base"”, "“//mojo/shell/public/cpp”" ]
+      deps = [ "“//base"”, "“//services/service_manager/public/cpp”" ]
       data_deps = [ “":manifest"” ]
     }
 
     service_manifest(“"manifest"”) {
       name = "“app"”
       source = “"app_manifest.json”"
     }
 
 What does all this do? Building the app target produces two files in the output
 directory: app/app.library and app/manifest.json. app.library is a DSO loaded by
 the Service Manager in its own process when another service connects to the
 “mojo:app” name. This is not the only way (nor even the most likely one) you can
 implement a Service, but it’s the simplest and easiest to reason about.
 
 This service doesn’t do much. Its implementation of OnStart() is empty, and its
 implementation of OnConnect just returns true to allow the inbound connection to
 complete. Let’s study the parameters to these methods though, since they’ll be
 important as we begin to do more in our service.
 
 ##### OnStart Parameters
 
-###### const shell::Identity& identity
+###### const service_manager::Identity& identity
 This is the identity this service is known to the Service Manager as. It
 includes the service’s Name, User ID and Instance Name.
 
 ##### OnConnect Parameters
 
-###### shell::Connection* connection
+###### service_manager::Connection* connection
 This is a pointer to an object that encapsulates the connection with a remote
 service. The service uses this object to learn about the service at the remote
 end, to bind interfaces from it, and to expose interfaces to it. The
 “Connection” concept is implemented under the hood by a pair of
-shell.mojom.InterfaceProviders - this is the physical link between the service
+service_manager.mojom.InterfaceProviders - this is the physical link between the service
 that give the Connection its utility. The Connection object is owned by the
 caller of OnConnect, and will outlive the underlying pipes.
 
 The service can decide to block the connection outright by returning false from
 this method. In that scenario the underlying pipes will be closed and the remote
 end will see an error and have the chance to recover.
 
 Before we add any functionality to our service, such as exposing an interface,
 we should look at how we connect to another service and bind an interface from
 it. This will lay the groundwork to understanding how to export an interface.
 
 ### Connecting
 
 Once we have a Connector, we can connect to other services and bind interfaces
 from them. In the trivial app above we can do this directly in OnStart:
 
-    void OnStart(const shell::Identity& identity) override {
-      scoped_ptr<shell::Connection> connection = 
+    void OnStart(const service_manager::Identity& identity) override {
+      scoped_ptr<service_manager::Connection> connection =
           connector()->Connect(“"mojo:service"”);
       mojom::SomeInterfacePtr some_interface;
       connection->GetInterface(&some_interface);
       some_interface->Foo();
     }
 
 This assumes an interface called “mojo.SomeInterface” with a method “Foo()”
 exported by another Mojo client identified by the name “mojo:service”.
 
 What is happening here? Let’s look line-by-line
 
 
-    scoped_ptr<shell::Connection> connection = 
+    scoped_ptr<service_manager::Connection> connection =
         connector->Connect("“mojo:service”");
 
 This asks the Service Manager to open a connection to the service named
 “mojo:service”. The Connect() method returns a Connection object similar to the
 one received by OnConnect() - in fact this Connection object binds the other
 ends of the pipes of the Connection object received by OnConnect in the remote
 service. This time, the caller of Connect() takes ownership of the Connection,
 and when it is destroyed the connection (and the underlying pipes) is closed. A
 note on this later.
 
@@ skipping 41 matching lines @@
 `//mojo/public/tools/bindings/mojom.gni`. Once we do that and look at the
 output, we can see that the C++ class mojom::SomeInterface is generated and can
 be #included from the same path as the .mojom file at some_interface.mojom.h.
 In our implementation of the mojo:service client, we’ll need to derive from this
 class to implement the interface. But that’s not enough. We’ll also have to find
 a way to bind inbound requests to bind this interface to the object that
 implements it. Let’s look at a snippet of a class that does all of this:
 
 **service.cc:**
 
-    class Service : public shell::Service,
-                    public shell::InterfaceFactory<mojom::SomeInterface>,
+    class Service : public service_manager::Service,
+                    public service_manager::InterfaceFactory<mojom::SomeInterface>,
                     public mojom::SomeInterface {
      public:
       ..
 
-      // Overridden from shell::Service:
-      bool OnConnect(shell::Connection* connection) override {
+      // Overridden from service_manager::Service:
+      bool OnConnect(service_manager::Connection* connection) override {
         connection->AddInterface<mojom::SomeInterface>(this);
         return true;
       }
 
-      // Overridden from shell::InterfaceFactory<mojom::SomeInterface>:
-      void Create(shell::Connection* connection,
+      // Overridden from service_manager::InterfaceFactory<mojom::SomeInterface>:
+      void Create(service_manager::Connection* connection,
                   mojom::SomeInterfaceRequest request) override {
         bindings_.AddBinding(this, std::move(request));
       }
 
       // Overridden from mojom::SomeInterface:
       void Foo() override { /* .. */ }
 
       mojo::BindingSet<mojom::SomeInterface> bindings_;
     };
 
@@ skipping 122 matching lines @@
 
 (Note that we didn’t write a manifest for mojo:service. We’d need to do that
 too, though for this example we wouldn’t have to describe mojom.SomeInterface in
 the provided section of its capability spec, since it wasn’t part of a class.
 Connecting services like mojo:app just need to state that interface.)
 
 ### Testing
 
 Now that we’ve built a simple application and service, it’s time to write a test
 for them. The Shell client library provides a gtest base class
-**shell::test::ServiceTest** that makes writing integration tests of services
+**service_manager::test::ServiceTest** that makes writing integration tests of services
 straightforward. Let’s look at a simple test of our service:
 
     #include "“base/bind.h”"
     #include “"base/run_loop.h”"
-    #include “"mojo/shell/public/cpp/service_test.h”"
+    #include “"services/service_manager/public/cpp/service_test.h”"
     #include “"path/to/some_interface.mojom.h”"
 
     void QuitLoop(base::RunLoop* loop) {
       loop->Quit();
     }
 
-    class Test : public shell::test::ServiceTest {
+    class Test : public service_manager::test::ServiceTest {
      public:
-      Test() : shell::test::ServiceTest(“exe:service_unittest”) {}
+      Test() : service_manager::test::ServiceTest(“exe:service_unittest”) {}
       ~Test() override {}
     }
 
     TEST_F(Test, Basic) {
       mojom::SomeInterface some_interface;
       connector()->ConnectToInterface(“"mojo:service"”, &some_interface);
       base::RunLoop loop;
       some_interface->Foo(base::Bind(&QuitLoop, &loop));
       loop.Run();
     }
 
 The BUILD.gn for this test file looks like any other using the test() template.
-It must also depend on //services/service_manager/public/cpp:shell_test_support.
+It must also depend on
+//services/service_manager/public/cpp:service_test_support.
 
 ServiceTest does a few things, but most importantly it register the test itself
 as a Service, with the name you pass it via its constructor. In the example
 above, we supplied the name “exe:service_unittest”. This name is has no special
 meaning other than that henceforth it will be used to identify the test service.
 
 Behind the scenes, ServiceTest spins up the Service Manager on a background
 thread, and asks it to create an instance for the test service on the main
 thread, with the name supplied. ServiceTest blocks the main thread while the
 Service Manager thread does this initialization. Once the Service Manager has
 created the instance, it calls OnStart() (as for any other service), and the
 main thread continues, running the test. At this point accessors defined in
 service_test.h like connector() can be used to connect to other services.
 
 You’ll note in the example above I made Foo() take a callback, this is to give
 the test something interesting to do. In the mojom for SomeInterface we’d have
 the Foo() method return an empty response. In mojo:service, we’d have Foo() take
 the callback as a parameter, and run it. In the test, we spin a RunLoop until we
 get that response. In real world cases we can pass back state & validate
 expectations. You can see real examples of this test framework in use in the
 Service Manager’s own suite of tests, under //services/service_manager/tests.
 
 ### Packaging
 
 By default a .library statically links its dependencies, so having many of them
 will yield an installed product many times larger than Chrome today. For this
 reason it’s desirable to package several Services together in a single binary.
-The Service Manager provides an interface **shell.mojom.ServiceFactory**:
+The Service Manager provides an interface **service_manager.mojom.ServiceFactory**:
 
     interface ServiceFactory {
       CreateService(Service& service, string name);
     };
 
 When implemented by a service, the service becomes a “package” of other
 services, which are instantiated by this interface. Imagine we have two services
 mojo:service1 and mojo:service2, and we wish to package them together in a
 single package mojo:services. We write the Service implementations for
 mojo:service1 and mojo:service2, and then a Service implementation for
 mojo:services - the latter implements ServiceFactory and instantiates the other
 two:
 
-    using shell::mojom::ServiceFactory;
-    using shell::mojom::ServiceRequest;
+    using service_manager::mojom::ServiceFactory;
+    using service_manager::mojom::ServiceRequest;
 
-    class Services : public shell::Service,
-                     public shell::InterfaceFactory<ServiceFactory>,
+    class Services : public service_manager::Service,
+                     public service_manager::InterfaceFactory<ServiceFactory>,
                      public ServiceFactory {
 
       // Expose ServiceFactory to inbound connections and implement
       // InterfaceFactory to bind requests for it to this object.
       void CreateService(ServiceRequest request,
                          const std::string& name) {
         if (name == “mojo:service1”)
           new Service1(std::move(request));
         else if (name == “mojo:service2”)
           new Service2(std::move(request));
@@ skipping 36 matching lines @@
     packaged_services = [ “"service1”", “"service2"” ]
 
 The deps line lists the service_manifest targets for the packaged services to be
 consumed, and the packaged_services line provides the service names, without the
 “mojo:” prefix. The presence of these two lines will cause the Manifest Collator
 script to run, merging the dependent manifests into the package manifest. You
 can study the resulting manifest to see what gets generated.
 
 At startup, the Service Manager will scan the package directory and consume the
 manifests it finds, so it can learn about how to resolve aliases that it might
-encounter subsequently. 
+encounter subsequently.
 
 ### Executables
 
 Thus far, the examples we’ve covered have packaged Services in .library files.
 It’s also possible to have a conventional executable provide a Service. There
 are two different ways to use executables with the Service Manager, the first is
 to have the Service Manager start the executable itself, the second is to have
 some other executable start the process and then tell the Service Manager about
 it. In both cases, the target executable has to perform a handshake with the
 Service Manager early on so it can bind the Service request the Service Manager
 sends it.
 
 Assuming you have an executable that properly initializes the Mojo EDK, you add
 the following lines at some point early in application startup to establish the
 connection with the Service Manager:
 
     #include “"services/service_manager/public/cpp/service.h”"
     #include “"services/service_manager/public/cpp/service_context.h”"
     #include “"services/service_manager/runner/child/runner_connection.h”"
 
-    class MyClient : public shell::Service {
+    class MyClient : public service_manager::Service {
     ..
     };
 
-    shell::mojom::ServiceRequest request;
-    scoped_ptr<shell::RunnerConnection> connection(
-       shell::RunnerConnection::ConnectToRunner(
+    service_manager::mojom::ServiceRequest request;
+    scoped_ptr<service_manager::RunnerConnection> connection(
+       service_manager::RunnerConnection::ConnectToRunner(
             &request, ScopedMessagePipeHandle()));
     MyService service;
-    shell::ServiceContext context(&service, std::move(request));
+    service_manager::ServiceContext context(&service, std::move(request));
 
 What’s happening here? The Service/ServiceContext usage should be familiar from
 our earlier examples. The interesting part here happens in
 `RunnerConnection::ConnectToRunner()`. Before we look at what ConnectToRunner
 does, it’s important to cover how this process is launched. In this example,
 this process is launched by the Service Manager. This is achieved through the
 use of the “exe” Service Name type. The Service Names we’ve covered thus far
 have looked like “mojo:foo”. The “mojo” prefix means that the Shell should look
 for a .library file at “foo/foo.library” alongside the Service Manager
 executable. If the code above was linked into an executable “app.exe” alongside
@@ skipping 24 matching lines @@
     base::FilePath target_path;
     base::PathService::Get(base::DIR_EXE, &target_path);
     target_path = target_path.Append(FILE_PATH_LITERAL("“target.exe"”));
     base::CommandLine target_command_line(target_path);
 
     mojo::edk::PlatformChannelPair pair;
     mojo::edk::HandlePassingInformation info;
     pair.PrepareToPassClientHandleToChildProcess(&target_command_line, &info);
 
     std::string token = mojo::edk::GenerateRandomToken();
-    target_command_line.AppendSwitchASCII(switches::kPrimordialPipeToken, 
+    target_command_line.AppendSwitchASCII(switches::kPrimordialPipeToken,
                                           token);
 
     mojo::ScopedMessagePipeHandle pipe =
         mojo::edk::CreateParentMessagePipe(token);
 
-    shell::mojom::ServiceFactoryPtr factory;
+    service_manager::mojom::ServiceFactoryPtr factory;
     factory.Bind(
-        mojo::InterfacePtrInfo<shell::mojom::ServiceFactory>(
+        mojo::InterfacePtrInfo<service_manager::mojom::ServiceFactory>(
             std::move(pipe), 0u));
-    shell::mojom::PIDReceiverPtr receiver;
+    service_manager::mojom::PIDReceiverPtr receiver;
 
-    shell::Identity target(“"exe:target”",shell::mojom::kInheritUserID);
-    shell::Connector::ConnectParams params(target);
-    params.set_client_process_connection(std::move(factory), 
+    service_manager::Identity target(“"exe:target”",service_manager::mojom::kInheritUserID);
+    service_manager::Connector::ConnectParams params(target);
+    params.set_client_process_connection(std::move(factory),
                                          GetProxy(&receiver));
-    scoped_ptr<shell::Connection> connection = connector->Connect(&params);
+    scoped_ptr<service_manager::Connection> connection = connector->Connect(&params);
 
     base::LaunchOptions options;
     options.handles_to_inherit = &info;
     base::Process process = base::LaunchProcess(target_command_line, options);
     mojo::edk::ChildProcessLaunched(process.Handle(), pair.PassServerHandle());
 
 That’s a lot. But it boils down to these steps:
 1. Creating the message pipe to connect the target process and the Service
 Manager.
 2. Putting the server end of the pipe onto the command line to the target
 process.
 3. Binding the client end to a ServiceFactoryPtr, constructing an Identity for
 the target process and passing both through Connector::Connect().
 4. Starting the process with the configured command line.
 
 In this example the target executable could be the same as the previous example.
 
-A word about process lifetimes. Processes created by the shell are managed by
-the Service Manager. While a service-launched process may quit itself at any
-point, when the Service Manager shuts down it will also shut down any process it
-started. Processes created by services themselves are left to those services to
-manage.
+A word about process lifetimes. Processes created by the Service Manager are
+also managed by the Service Manager. While a service-launched process may quit
+itself at any point, when the Service Manager shuts down it will also shut down
+any process it started. Processes created by services themselves are left to
+those services to manage.
 
 ***
 
 TBD:
 
 Instances & Processes
 
 Client lifetime strategies
 
 Process lifetimes.
 
 Writing tests (ShellTest)
 Under the Hood
 Four major components: Shell API (Mojom), Shell, Catalog, Shell Client Lib.
 The connect flow, catalog, etc.
 Capability brokering in the shell
 Userids
 
 Finer points:
 
 Mojo Names: mojo, exe
 Exposing services on outbound connections