Merge lp:~clint-fewbar/gearmand/document-protocol into lp:gearmand

[Clint Byrum]

Document new undocumented commands in PROTOCOL

[lp:~clint-fewbar/gearmand/document-protocol]

910. By Clint Byrum on 2015-04-16

Add documentation for the purpose of Unique ID

[Clint Byrum (clint-fewbar)]

This was merged upstream in https://github.com/gearman/gearmand/commit/eabf8a01030a16c80bada1e06c4162f8d129a5e8

Unmerged revisions

910. By Clint Byrum on 2015-04-16

Add documentation for the purpose of Unique ID

909. By Clint Byrum on 2015-03-17

Add basic documentation of undocumented protocol pieces.

It seems that the protocol added a few more commands and responses in
recent times, and they should at least be documented. The way that REDUCER
is used is still somewhat confusing and needs better documentation as
to what is expected, but at least an implementor can handle the commands
with a graceful error now.

=== modified file 'PROTOCOL'
--- PROTOCOL	2012-05-04 03:46:04 +0000
+++ PROTOCOL	2015-04-16 00:11:24 +0000
@@ -102,6 +102,13 @@
                     34  SUBMIT_JOB_LOW_BG   REQ    Client
                     35  SUBMIT_JOB_SCHED    REQ    Client
                     36  SUBMIT_JOB_EPOCH    REQ    Client
+                    37  SUBMIT_REDUCE_JOB   REQ    Client
+                    38  SUBMIT_REDUCE_JOB_BACKGROUND REQ    Client
+                    39  GRAB_JOB_ALL        REQ    Worker
+                    40  JOB_ASSIGN_ALL      RES    Worker
+                    41  GET_STATUS_UNIQUE   REQ    Client
+                    42  STATUS_RES_UNIQUE   RES    Client
+
 
 4 byte size       - A big-endian (network-order) integer containing
                     the size of the data being sent after the header.
@@ -171,9 +178,26 @@
     always take precedence, and jobs submitted with the normal versions
     take precedence over the LOW versions.
 
-    Arguments:
-    - NULL byte terminated function name.
-    - NULL byte terminated unique ID.
+    The unique ID can be used by the server to reduce queue length. If a
+    job with the same Unique ID has already been submitted, the server
+    may attach this request to the already existing job. This includes
+    jobs already in progress, in which case non-background jobs will be
+    sent the same result as background jobs. This is known commonly as
+    "coalescing".
+
+    Arguments:
+    - NULL byte terminated function name.
+    - NULL byte terminated unique ID.
+    - Opaque data that is given to the function as an argument.
+
+SUBMIT_REDUCE_JOB, SUBMIT_REDUCE_JOB_BACKGROUND
+
+    Works like the other SUBMIT_JOB commands, but adds a reducer argument.
+
+    Arguments:
+    - NULL byte terminated function name.
+    - NULL byte terminated unique ID.
+    - NULL byte terminated reducer.
     - Opaque data that is given to the function as an argument.
 
 SUBMIT_JOB_SCHED
@@ -209,6 +233,13 @@
     Arguments:
     - Job handle that was given in JOB_CREATED packet.
 
+GET_STATUS_UNIQUE
+
+    A client issues this to get status information for a submitted job.
+
+    Arguments:
+    - Unique value that was given when job was submitted.
+
 OPTION_REQ
 
     A client issues this to set an option for the connection in the
@@ -255,6 +286,22 @@
     - NULL byte terminated percent complete numerator.
     - Percent complete denominator.
 
+STATUS_RES_UNIQUE
+
+    This is sent in response to a GET_STATUS_UNIQUE request. This is
+    used by clients that have submitted a job with SUBMIT_JOB_BG to see
+    if the job has been completed, and if not, to get the percentage
+    complete.
+
+    Arguments:
+    - NULL byte terminated job handle.
+    - NULL byte terminated known status, this is 0 (false) or 1 (true).
+    - NULL byte terminated running status, this is 0 (false) or 1
+      (true).
+    - NULL byte terminated percent complete numerator.
+    - NULL byte terminated percent complete denominator.
+    - Count of clients waiting.
+
 OPTION_RES
 
     Successful response to the OPTION_REQ request.
@@ -329,6 +376,13 @@
     Arguments:
     - None.
 
+GRAB_JOB_ALL
+
+    Just like GRAB_JOB_UNIQ, but return JOB_ASSIGN_ALL when there is a job.
+
+    Arguments:
+    - None.
+
 WORK_DATA
 
     This is sent to update the client with data from a running job. A
@@ -456,6 +510,17 @@
     - NULL byte terminated unique ID.
     - Opaque data that is given to the function as an argument.
 
+JOB_ASSIGN_ALL
+
+    This is given in response to a GRAB_JOB_ALL request and acts
+    just like JOB_ASSIGN_UNIQ but with the reducer returned.
+
+    Arguments:
+    - NULL byte terminated job handle.
+    - NULL byte terminated function name.
+    - NULL byte terminated unique ID.
+    - NULL byte terminated reducer.
+    - Opaque data that is given to the function as an argument.
 
 Administrative Protocol
 -----------------------