From 2abe87472c12e64904bd6dd06b9ad7c5595490ae Mon Sep 17 00:00:00 2001
From: David Wilson <dw@botanicus.net>
Date: Fri, 23 Mar 2018 09:31:11 +0545
Subject: [PATCH] issue #162: docs: begin documenting mitogen.service

---
 docs/services.rst | 85 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 docs/services.rst

diff --git a/docs/services.rst b/docs/services.rst
new file mode 100644
index 00000000..c121734a
--- /dev/null
+++ b/docs/services.rst
@@ -0,0 +1,85 @@
+
+.. currentmodule:: mitogen.service
+
+
+Service Framework
+=================
+
+Mitogen includes a simple framework for implementing services exposed to other
+contexts, with built-in subclasses that capture some common service models.
+This is a work in progress, and new functionality will be added as a common use
+for it is is found.
+
+
+Overview
+--------
+
+
+Example
+-------
+
+.. code-block:: python
+
+    import mitogen
+    import mitogen.service
+
+
+    class FileService(mitogen.service.Service):
+        """
+        Simple file server, for demonstration purposes only! Use of this in
+        real code would be a security vulnerability as it would permit children
+        to read arbitrary files from the master's disk.
+        """
+        handle = 500
+        required_args = {
+            'path': str
+        }
+
+        def dispatch(self, args, msg):
+            with open(args['path'], 'r') as fp:
+                return fp.read()
+
+
+    def download_file(context, path):
+        s = mitogen.service.call(context, FileService.handle, {
+            'path': path
+        })
+
+        with open(path, 'w') as fp:
+            fp.write(s)
+
+
+    @mitogen.core.takes_econtext
+    def download_some_files(paths, econtext):
+        for path in paths:
+            download_file(econtext.master, path)
+
+
+    @mitogen.main()
+    def main(router):
+        pool = mitogen.service.Pool(router, size=1, services=[
+            FileService(router),
+        ])
+
+        remote = router.ssh(hostname='k3')
+        remote.call(download_some_files, [
+            '/etc/passwd',
+            '/etc/hosts',
+        ])
+        pool.stop()
+
+
+Reference
+---------
+
+.. autofunction:: mitogen.service.Service
+
+.. autoclass:: mitogen.service.Service
+    :members:
+
+.. autoclass:: mitogen.service.DeduplicatingService
+    :members:
+
+.. autoclass:: mitogen.service.Pool
+    :members:
+