From a6cd5df34797f7ee441ad77d72c2af2055fbd5cf Mon Sep 17 00:00:00 2001
From: Elena Ezhova <eezhova@mirantis.com>
Date: Mon, 13 Jul 2015 20:03:57 +0300
Subject: [PATCH] Add usage documentation for oslo_service.service module

This change adds description of various ways of launching a service
and provides information on supported signals.

Description of launcher classes is moved from oslo_service.service.py
to usage.rst

Change-Id: I7b6a5337de4c25ad16bd33be48daa8ef8bf3b6f5
---
 doc/source/index.rst    |  2 +-
 doc/source/usage.rst    | 91 +++++++++++++++++++++++++++++++++++++++++
 oslo_service/service.py | 13 +-----
 3 files changed, 93 insertions(+), 13 deletions(-)

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 6ac47c04..538b5852 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -5,7 +5,7 @@ Welcome to oslo.service's documentation!
 Library for running OpenStack services
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    installation
    usage
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 0b1252ac..0750fb55 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -65,3 +65,94 @@ files.
     $ oslo-config-generator --namespace oslo.service.service \
     --namespace oslo.service.periodic_task \
     --namespace oslo.service.sslutils
+
+Launching and controlling services
+==================================
+
+oslo_service.service module provides tools for launching OpenStack services and controlling their lifecycles.
+
+A service is an instance of any class that subclasses :py:class:`oslo_service.service.ServiceBase`.
+:py:class:`ServiceBase <oslo_service.service.ServiceBase>` is an abstract class that defines an interface every
+service should implement. :py:class:`oslo_service.service.Service` can serve as a base for constructing new services.
+
+Launchers
+~~~~~~~~~
+
+oslo_service.service module provides two launchers for running services:
+
+    * :py:class:`oslo_service.service.ServiceLauncher` - used for running one or more service in
+      a parent process.
+    * :py:class:`oslo_service.service.ProcessLauncher` - forks a given number of workers in which
+      service(s) are then started.
+
+It is possible to initialize whatever launcher is needed and then launch a service using it.
+
+::
+
+    from oslo_config import cfg
+    from oslo_service import service
+
+    CONF = cfg.CONF
+
+
+    service_launcher = service.ServiceLauncher(CONF)
+    service_launcher.launch_service(service.Service())
+
+    process_launcher = service.ProcessLauncher(CONF, wait_interval=1.0)
+    process_launcher.launch_service(service.Service(), workers=2)
+
+Or one can simply call :func:`oslo_service.service.launch` which will automatically pick an appropriate launcher
+based on a number of workers that are passed to it (ServiceLauncher in case workers=1 or None and ProcessLauncher in
+other case).
+
+::
+
+    from oslo_config import cfg
+    from oslo_service import service
+
+    CONF = cfg.CONF
+
+    launcher = service.launch(CONF, service.Service(), workers=3)
+
+*NOTE:* Please be informed that it is highly recommended to use no more than one instance of ServiceLauncher and
+ProcessLauncher classes per process.
+
+Signal handling
+~~~~~~~~~~~~~~~
+
+oslo_service.service provides handlers for such signals as SIGTERM and SIGHUP.
+
+SIGTERM is used for graceful termination of services. This can allow a server to wait for all clients to close
+connections while rejecting new incoming requests. To force instantaneous termination SIGINT signal must be sent.
+
+On receiving SIGHUP configuration files are reloaded and a service is being reset and started again.Thus, SIGHUP
+can be used for changing config options on the go. To achieve this each service should implement a *reset* method
+which actually enforces changes to config options values.
+
+Below is the example of a service with a reset method that allows reloading logging options by sending a SIGHUP.
+
+::
+
+    from oslo_config import cfg
+    from oslo_log import log as logging
+    from oslo_service import service
+
+    CONF = cfg.CONF
+
+    LOG = logging.getLogger(__name__)
+
+    class FooService(service.ServiceBase):
+
+        def start(self):
+            pass
+
+        def wait(self):
+            pass
+
+        def stop(self):
+            pass
+
+        def reset(self):
+            logging.setup(cfg.CONF, 'foo')
+
+
diff --git a/oslo_service/service.py b/oslo_service/service.py
index e933eb38..03153c34 100644
--- a/oslo_service/service.py
+++ b/oslo_service/service.py
@@ -15,18 +15,7 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
-"""Generic Node base class for all workers that run on hosts.
-
-This module provides two launchers for running services:
-
-    * ServiceLauncher - used for running one or more service in
-      a parent process.
-    * ProcessLauncher - forks a given number of workers in which
-      service(s) are then started.
-
-Please be informed that it is highly recommended to use no more than
-one instance of ServiceLauncher and ProcessLauncher classes per process.
-"""
+"""Generic Node base class for all workers that run on hosts."""
 
 import abc
 import copy