From b473ea73145a8eff91e3807b91530a4a5f203c6c Mon Sep 17 00:00:00 2001
From: dlavigne <dru@freebsd.org>
Date: Fri, 29 Apr 2016 10:58:56 -0400
Subject: [PATCH] Add new dispatcher class.

---
 api/classes/dispatcher.rst | 81 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 api/classes/dispatcher.rst

diff --git a/api/classes/dispatcher.rst b/api/classes/dispatcher.rst
new file mode 100644
index 0000000..f21d1bd
--- /dev/null
+++ b/api/classes/dispatcher.rst
@@ -0,0 +1,81 @@
+.. _dispatcher:
+
+dispatcher
+**********
+
+The dispatcher class is used to spin up external processes on demand, such as a user running a custom system setup script.
+
+Every dispatcher class request contains the following parameters:
+
++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+| **Parameter**                   | **Value**     | **Description**                                                                                                      |
+|                                 |               |                                                                                                                      |
++=================================+===============+======================================================================================================================+
+| id                              |               | any unique value for the request; examples include a hash, checksum, or uuid                                         |
+|                                 |               |                                                                                                                      |
++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+| name                            | dispatcher    |                                                                                                                      |
+|                                 |               |                                                                                                                      |
++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+| namespace                       | rpc           |                                                                                                                      |
+|                                 |               |                                                                                                                      |
++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+| action                          |               | supported actions include "list"                                                                                     |
+|                                 |               |                                                                                                                      |
++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+
+The rest of this section provides examples of the available *actions* for each type of request, along with their responses. 
+
+.. index:: list, dispatcher
+
+.. _List Processes:
+
+List Processes
+==============
+
+The "list" action lists all the currently running or pending processes within the dispatcher queues. Possible queues are "no_queue", "pkg_queue", and "iocage_queue".
+
+**REST Request**
+
+.. code-block:: json
+
+ PUT /rpc/dispatcher
+ {
+   "action" : "list"
+ }
+
+**WebSocket Request**
+
+.. code-block:: json
+
+ {
+   "args" : {
+      "action" : "list"
+   },
+   "namespace" : "rpc",
+   "name" : "dispatcher",
+   "id" : "fooid"
+ }
+
+**Response**
+
+.. code-block:: json
+
+ {
+  "args": {
+    "jobs": {
+      "pkg_queue": {
+        "sysadm_pkg_install-{9c079421-ace9-4b6e-8870-d023b48f4c49}": {
+          "commands": [
+            "pkg install -y --repository \"pcbsd-major\" misc/pcbsd-meta-mate"
+          ],
+          "queue_position": "0",
+          "state": "running"
+        }
+      }
+    }
+  },
+  "id": "fooid",
+  "name": "response",
+  "namespace": "rpc"
+ }
\ No newline at end of file