documentation: add task state diagram

The diagram gives a concise and holistic view of all the task states
and what method triggers each transition between the states.

Closes #123

Author: veod32

README.md

@@ -21,6 +21,7 @@ align="right">
   * [Fields of the \_queue\_taken\_2 space](#fields-of-the-_queue_taken_2-space)
   * [Fields of the \_queue\_session\_ids space](#fields-of-the-_queue_session_ids-space)
   * [Fields of the space associated with each queue](#fields-of-the-space-associated-with-each-queue)
+* [Task state diagram](#task-state-diagram)
 * [Installing](#installing)
 * [Using the queue module](#using-the-queue-module)
   * [Initialization](#initialization)
@@ -295,14 +296,32 @@ The `task_state` field takes one of the following values
 (different queue types support different
 sets of `task_state` values, so this is a superset):
 
-* 'r' - the task is ready for execution (the first consumer executing
+* 'r' - the task is **ready** for execution (the first consumer executing
 a `take` request will get it)
-* 't' - the task has been taken by a consumer
-* '-' - the task has been executed (a task is removed from the queue
-after it
-   has been executed, so this value will rarely be seen)
-* '!' - the task is buried (disabled temporarily until further changes)
-* '~' - the task is delayed for some time
+* 't' - the task has been **taken** by a consumer
+* '-' - the task has been **executed (done)** (a task is removed from the queue
+after it has been executed, so this value will rarely be seen)
+* '!' - the task is **buried** (disabled temporarily until further changes)
+* '~' - the task is **delayed** for some time.
+
+For details on the state transitions, refer to [Task state diagram](#task-state-diagram).
+
+# Task state diagram
+
+The following diagram shows possible transitions between the [task states](#fields-of-the-space-associated-with-each-queue).
+For information on the transition triggers, refer to:
+
+* [put()](#putting-a-task-in-a-queue)
+* [release()](#releasing-a-task)
+* [take()](#taking-a-task-from-the-queue-consuming)
+* [kick()](#kicking-a-number-of-tasks)
+* [bury()](#burying-a-task)
+* [ack()](#acknowledging-the-completion-of-a-task)
+* [delete()](#deleting-a-task)
+* description of the `timeout`, `ttl timeout`, and `ttr timeout` options in
+the sections of the corresponding [queue types](#queue-types).
+
+![Task state diagram](./doc/images/statediagram.svg)
 
 # Installing
 

doc/images/statediagram.svg

@@ -0,0 +1,27 @@
+/' This code is for generating the task state diagram in SVG format.
+Use any PlantUML rendering service, for example, https://www.planttext.com/.
+To generate the diagram on the page of this service:
+1.  In the left pane, copy and paste the code or select this source file
+    statediagram.puml with the "File Manager" button.
+2.  Click "Refresh". The resulting diagram is displayed in the right pane.
+3.  Click SVG link below the diagram view and download the diagram file.
+4.  Rename the file into "statediagram.svg" and upload in the ./doc/images/
+    folder.
+'/
+
+@startuml
+[*]     -down->  READY   : put()
+[*]     -down->  DELAYED : put('my_task_data',\n{ delay = delay })
+READY   -down->  TAKEN   : take()
+READY   -down->  DONE    : delete() /\nttl timeout
+READY   -down->  BURIED  : bury()
+TAKEN   -up->    READY   : release() /\nttr timeout
+TAKEN   -left->  DELAYED : release\n(id, { delay = delay })
+TAKEN   -down->  DONE    : ack() / delete()
+TAKEN   -right-> BURIED  : bury()
+BURIED  -down->  DONE    : delete() /\nttl timeout
+BURIED  -up->    READY   : kick()
+DELAYED -up->    READY   : timeout
+DELAYED -down->  DONE    : delete()
+DONE    -down->  [*]     : remove executed task
+@enduml