issue #162: docs: begin documenting mitogen.service

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:
+