qos: add pictures to the documentation

Change-Id: If7a3bbe653aec3570ecc0450f7841594de39bee0

diff --git a/configs/15-qos.conf b/configs/15-qos.conf
index 9c4a0da..6ff1b8a 100644 (file)
--- a/configs/15-qos.conf
+++ b/configs/15-qos.conf
@@ -34,27 +34,134 @@ qos_threshold_reapply_logs=5
 #                            each clients used up their limits.
 #              For example if there are 4 clients, and they sent
 #              4/8/12/16 logs respectively (reaching threshold 40)
-#              their limits will be 5/10/15/20 (if max is 50).
+#              their limits will be 20/40/60/80 (if max is 200).
+#
+#
+# Here's a hydraulic interpretation (think of the limits as of water filling
+# connected containers):
+#
+#            ┌   ┐         ┌     ┐           ┌ ┐         ┌       ┐
+#            │   │         │     │           │ │         │       │
+#            │   │         │     │           │ │         │       │
+#            │   │         │     │           │ │         │       │
+#            │   │         │     │           │ │         │       │
+#            │   │         │     │           │ │         │       │
+#            │   │         │     │           │ │         │       │
+#            │   │         │     │           │ │         │       │
+#            │   │         │     │           │ │         │       │
+#            │▒▒▒│         │▒▒▒▒▒│           │▒│         │▒▒▒▒▒▒▒│
+#            │▒▒▒│         │▒▒▒▒▒│           │▒│         │▒▒▒▒▒▒▒│
+#            └─╥─┘         └──╥──┘           └╥┘         └───╥───┘
+#              ╚══════════════╩═══════════════╩══════════════╝
+#
+#             8/40          12/60            4/20          16/80
+#
 #
 #       "equal" : max limit is distributed equally.
 #              For example if there are 4 clients, and they sent
-#              4/8/12/16 logs respectively (reaching threshold 40)
-#              their limits will be 13/13/13/13 (if max is 50).
+#              1/17/42/66 logs respectively, their limits will
+#              be 50/50/50/50 (if max is 200).
+#
+#
+#
+#
+#                            ▒▒▒▒▒
+#                            ▒▒▒▒▒
+# 50 (= 200 / 4)_____________▒▒▒▒▒________________________________
+#                            ▒▒▒▒▒
+#                            ▒▒▒▒▒
+#                            ▒▒▒▒▒                           ▒▒▒▒▒
+#                            ▒▒▒▒▒                           ▒▒▒▒▒
+#                            ▒▒▒▒▒                           ▒▒▒▒▒
+#                            ▒▒▒▒▒                           ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒           ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒           ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒           ▒▒▒▒▒
+#            ▒▒▒▒▒           ▒▒▒▒▒           ▒▒▒▒▒           ▒▒▒▒▒
+#              1              66               17             42
+#
+#
+#
 #
 #       "equal_dual" : any client under the "equal" limit
 #                      can log freely, any remaining throughput is
 #                      distributed equally among the rest
 #              For example if there are 3 clients, and they sent
-#              20/35/60 logs (max throughput 100), they will get
-#              --/40/40 limits respectively: 20 < 33, remaining 80
+#              20/85/120 logs (max throughput 200), they will get
+#              --/90/90 limits respectively: 20 < 67, remaining 180
 #               gets split equally
 #
+#
+#                                            ▒▒▒▒▒
+#                                            ▒▒▒▒▒
+#                                            ▒▒▒▒▒
+#                                            ▒▒▒▒▒
+#                                            ▒▒▒▒▒
+# 90 (= (200 - 20) / 2)______________________▒▒▒▒▒___
+#                                            ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒
+# 67 (= 200 / 3)_______      ▒▒▒▒▒           ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒
+#                            ▒▒▒▒▒           ▒▒▒▒▒
+#            ▒▒▒▒▒           ▒▒▒▒▒           ▒▒▒▒▒
+#            ▒▒▒▒▒           ▒▒▒▒▒           ▒▒▒▒▒
+#            ▒▒▒▒▒           ▒▒▒▒▒           ▒▒▒▒▒
+#            ▒▒▒▒▒           ▒▒▒▒▒           ▒▒▒▒▒
+#             20              85             120
+#
+#
+#
+#
 #       "equal_multi" (default) : similar to the above, but any client
 #              not reaching its limit is also unlimited, increasing it.
 #              For example if there are 3 clients, and they sent
-#              20/35/60 logs (max throughput 100), they will get
-#              --/--/45 limits respectively: 20 < 33, but then the
-#              remaining average becomes 40 (like in dual) and 35 < 40.
+#              20/85/120 logs (max throughput 200), they will get
+#              --/--/95 limits respectively: 20 < 67, but then the
+#              remaining average becomes 90 (like in dual) and 85 < 90,
+#              and finally average becomes 95 ((200 - 20 - 85) / 1) and 120 > 95,
+#              so it stays at this level.
+#
+#
+# Here's a hydraulic interpretation:
+#
+#                                           ┌─────┐
+#                                           │     │
+#                                           │     │
+#                                           │     │
+#                                           │     │
+# 95 (= (200 - 20 - 85) / 1)________________│     │__
+# 90 (= (200 - 20) / 2)________________     │▒▒▒▒▒│
+#                           ┌─────┐         │▒▒▒▒▒│
+#                           │▒▒▒▒▒│         │▒▒▒▒▒│
+#                           │▒▒▒▒▒│         │▒▒▒▒▒│
+#                           │▒▒▒▒▒│         │▒▒▒▒▒│
+# 67 (= 200 / 3)________    │▒▒▒▒▒│         │▒▒▒▒▒│
+#                           │▒▒▒▒▒│         │▒▒▒▒▒│
+#                           │▒▒▒▒▒│         │▒▒▒▒▒│
+#                           │▒▒▒▒▒│         │▒▒▒▒▒│
+#                           │▒▒▒▒▒│         │▒▒▒▒▒│
+#                           │▒▒▒▒▒│         │▒▒▒▒▒│
+#                           │▒▒▒▒▒│         │▒▒▒▒▒│
+#                           │▒▒▒▒▒│         │▒▒▒▒▒│
+#                           │▒▒▒▒▒│         │▒▒▒▒▒│
+# -20-      ┌─────┐         │▒▒▒▒▒│         │▒▒▒▒▒│
+#           │▒▒▒▒▒│         │▒▒▒▒▒│         │▒▒▒▒▒│
+#           │▒▒▒▒▒│         │▒▒▒▒▒│         │▒▒▒▒▒│
+#           │▒▒▒▒▒│         │▒▒▒▒▒│         │▒▒▒▒▒│
+# -0-       │▒▒▒▒▒│         │▒▒▒▒▒│         │▒▒▒▒▒│
+#           └──╥──┘         └──╥──┘         └──╥──┘
+#              ╚═══════════════╩═══════════════╝
+#             20              85              120
+#
 #
 #       "proportional_talmud" : Talmudic contested garment rule.
 #              It interpolates between equal shares and equal dropped
@@ -64,7 +171,46 @@ qos_threshold_reapply_logs=5
 #               100/200/300 logs, max throughput 200: 50/ 75/ 75
 #               100/200/300 logs, max throughput 300: 50/100/150
 #               100/200/300 logs, max throughput 400: 50/125/225
-#               100/200/300 logs, max throughput 500: 66/166/266
+#               100/200/300 logs, max throughput 500: 67/167/267
+#
+#
+# Here's a hydraulic interpretation:
+#
+#
+# -300-     ┌─────┐         ┌─────┐         ┌─────┐
+#           │     │         │     │         │     │
+#           │     │         │     │         │     │
+#           │     │         │     │         │     │
+#           │▓▓▓▓▓│         │▓▓▓▓▓│         │▓▓▓▓▓│<- when adding 150 more to the
+# -250-     └──╥──┘         │▓▓▓▓▓│         │▓▓▓▓▓│   previous total of 350, the
+#              ║            │▓▓▓▓▓│         │▓▓▓▓▓│   levels turn out to be
+#              ║            │▓▓▓▓▓│         │▓▓▓▓▓│   67, 167, 267
+#              ║            │▓▓▓▓▓│         │▓▓▓▓▓│
+#              ║            │▓▓▓▓▓│         │▓▓▓▓▓│
+# -200-        ║            └──╥──┘         │▒▒▒▒▒│<- when adding 150 more to the
+#              ║               ║            │▒▒▒▒▒│   previous total of 200, most
+#              ║               ║            │▒▒▒▒▒│   of it goes to the third one
+#              ║               ║            │▒▒▒▒▒│   with the highest limit, for
+#              ║               ║            │▒▒▒▒▒│   levels of 50, 100 and 200
+# -150-        ║               ║            │▒▒▒▒▒│
+#              ║               ║            │▒▒▒▒▒│
+#              ║               ║            │▒▒▒▒▒│
+#              ║               ║            │▒▒▒▒▒│
+#              ║               ║            │▒▒▒▒▒│
+# -100-        ║            ┌──╨──┐         │▒▒▒▒▒│
+#              ║            │▒▒▒▒▒│         │▒▒▒▒▒│
+#              ║            │▒▒▒▒▒│         │▒▒▒▒▒│
+#              ║            │░░░░░│         │░░░░░│<- at 200 total, the levels
+#              ║            │░░░░░│         │░░░░░│   turn out to be 50, 75 and 75
+# -50-      ┌──╨──┐         │░░░░░│         │░░░░░│
+#           │░░░░░│         │░░░░░│         │░░░░░│
+#           │░░░░░│         │░░░░░│         │░░░░░│
+#           │░░░░░│         │░░░░░│         │░░░░░│
+#           │░░░░░│         │░░░░░│         │░░░░░│
+# -0-       └──╥──┘         └──╥──┘         └──╥──┘
+#              ╚═══════════════╩═══════════════╝
+#
+#
 #
 qos_method=equal_multi