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

Proposed by Clint Byrum on 2015-03-17
Status: Needs review
Proposed branch: lp:~clint-fewbar/gearmand/document-protocol
Merge into: lp:gearmand
Diff against target: 116 lines (+68/-3)
1 file modified
PROTOCOL (+68/-3)
To merge this branch: bzr merge lp:~clint-fewbar/gearmand/document-protocol
Reviewer Review Type Date Requested Status
Tangent Trunk 2015-03-17 Pending
Review via email: mp+253140@code.launchpad.net

Description of the change

Document new undocumented commands in PROTOCOL

To post a comment you must log in.
910. By Clint Byrum on 2015-04-16

Add documentation for the purpose of Unique ID

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.

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
=== modified file 'PROTOCOL'
--- PROTOCOL 2012-05-04 03:46:04 +0000
+++ PROTOCOL 2015-04-16 00:11:24 +0000
@@ -102,6 +102,13 @@
102 34 SUBMIT_JOB_LOW_BG REQ Client102 34 SUBMIT_JOB_LOW_BG REQ Client
103 35 SUBMIT_JOB_SCHED REQ Client103 35 SUBMIT_JOB_SCHED REQ Client
104 36 SUBMIT_JOB_EPOCH REQ Client104 36 SUBMIT_JOB_EPOCH REQ Client
105 37 SUBMIT_REDUCE_JOB REQ Client
106 38 SUBMIT_REDUCE_JOB_BACKGROUND REQ Client
107 39 GRAB_JOB_ALL REQ Worker
108 40 JOB_ASSIGN_ALL RES Worker
109 41 GET_STATUS_UNIQUE REQ Client
110 42 STATUS_RES_UNIQUE RES Client
111
105112
1064 byte size - A big-endian (network-order) integer containing1134 byte size - A big-endian (network-order) integer containing
107 the size of the data being sent after the header.114 the size of the data being sent after the header.
@@ -171,9 +178,26 @@
171 always take precedence, and jobs submitted with the normal versions178 always take precedence, and jobs submitted with the normal versions
172 take precedence over the LOW versions.179 take precedence over the LOW versions.
173180
174 Arguments:181 The unique ID can be used by the server to reduce queue length. If a
175 - NULL byte terminated function name.182 job with the same Unique ID has already been submitted, the server
176 - NULL byte terminated unique ID.183 may attach this request to the already existing job. This includes
184 jobs already in progress, in which case non-background jobs will be
185 sent the same result as background jobs. This is known commonly as
186 "coalescing".
187
188 Arguments:
189 - NULL byte terminated function name.
190 - NULL byte terminated unique ID.
191 - Opaque data that is given to the function as an argument.
192
193SUBMIT_REDUCE_JOB, SUBMIT_REDUCE_JOB_BACKGROUND
194
195 Works like the other SUBMIT_JOB commands, but adds a reducer argument.
196
197 Arguments:
198 - NULL byte terminated function name.
199 - NULL byte terminated unique ID.
200 - NULL byte terminated reducer.
177 - Opaque data that is given to the function as an argument.201 - Opaque data that is given to the function as an argument.
178202
179SUBMIT_JOB_SCHED203SUBMIT_JOB_SCHED
@@ -209,6 +233,13 @@
209 Arguments:233 Arguments:
210 - Job handle that was given in JOB_CREATED packet.234 - Job handle that was given in JOB_CREATED packet.
211235
236GET_STATUS_UNIQUE
237
238 A client issues this to get status information for a submitted job.
239
240 Arguments:
241 - Unique value that was given when job was submitted.
242
212OPTION_REQ243OPTION_REQ
213244
214 A client issues this to set an option for the connection in the245 A client issues this to set an option for the connection in the
@@ -255,6 +286,22 @@
255 - NULL byte terminated percent complete numerator.286 - NULL byte terminated percent complete numerator.
256 - Percent complete denominator.287 - Percent complete denominator.
257288
289STATUS_RES_UNIQUE
290
291 This is sent in response to a GET_STATUS_UNIQUE request. This is
292 used by clients that have submitted a job with SUBMIT_JOB_BG to see
293 if the job has been completed, and if not, to get the percentage
294 complete.
295
296 Arguments:
297 - NULL byte terminated job handle.
298 - NULL byte terminated known status, this is 0 (false) or 1 (true).
299 - NULL byte terminated running status, this is 0 (false) or 1
300 (true).
301 - NULL byte terminated percent complete numerator.
302 - NULL byte terminated percent complete denominator.
303 - Count of clients waiting.
304
258OPTION_RES305OPTION_RES
259306
260 Successful response to the OPTION_REQ request.307 Successful response to the OPTION_REQ request.
@@ -329,6 +376,13 @@
329 Arguments:376 Arguments:
330 - None.377 - None.
331378
379GRAB_JOB_ALL
380
381 Just like GRAB_JOB_UNIQ, but return JOB_ASSIGN_ALL when there is a job.
382
383 Arguments:
384 - None.
385
332WORK_DATA386WORK_DATA
333387
334 This is sent to update the client with data from a running job. A388 This is sent to update the client with data from a running job. A
@@ -456,6 +510,17 @@
456 - NULL byte terminated unique ID.510 - NULL byte terminated unique ID.
457 - Opaque data that is given to the function as an argument.511 - Opaque data that is given to the function as an argument.
458512
513JOB_ASSIGN_ALL
514
515 This is given in response to a GRAB_JOB_ALL request and acts
516 just like JOB_ASSIGN_UNIQ but with the reducer returned.
517
518 Arguments:
519 - NULL byte terminated job handle.
520 - NULL byte terminated function name.
521 - NULL byte terminated unique ID.
522 - NULL byte terminated reducer.
523 - Opaque data that is given to the function as an argument.
459524
460Administrative Protocol525Administrative Protocol
461-----------------------526-----------------------

Subscribers

People subscribed via source and target branches

to all changes: