From 6f276d22846f4b93abdfe7dfbbbf614c40325d88 Mon Sep 17 00:00:00 2001 From: oir Date: Sun, 5 Jan 2025 16:20:44 -0500 Subject: [PATCH 1/4] Document functional progress monitors --- README.md | 27 ++++++++ docs/README.md | 91 ++++++++++++++++++++++++- docs/index.html | 4 ++ docs/rec/lambda-dark.svg | 140 ++++++++++++++++++++++++++++++++++++++ docs/rec/lambda-light.svg | 140 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 401 insertions(+), 1 deletion(-) create mode 100644 docs/rec/lambda-dark.svg create mode 100644 docs/rec/lambda-light.svg diff --git a/README.md b/README.md index a9a78c0..2f92f27 100644 --- a/README.md +++ b/README.md @@ -230,6 +230,33 @@ __barkeep__ strives to be [non-intrusive](#non-intrusive-design). +- Use a function (e.g. lambda) to monitor progress, instead of a variable + (_credit: [jh0x](https://github.com/oir/barkeep/pull/97)_): + + ```cpp + unsigned long total_area = 10000; + unsigned long width = 0, height = 0; + auto bar = bk::ProgressBar([&] { return width * height; }, { + .total = total_area, + .message = "Sweeping area", + .speed = 1., + }); + while (width < 100 and height < 100) { + std::this_thread::sleep_for(70ms); + if (width < 100) { width++; } + if (height < 100) { height++; } + } + ``` + + Observe how a lambda is passed as the first argument as opposed to a variable + like `&width`. + + + + + + + - Combine diplays using `|` operator to monitor multiple variables: ```cpp diff --git a/docs/README.md b/docs/README.md index 4d0c385..f548867 100644 --- a/docs/README.md +++ b/docs/README.md @@ -34,6 +34,12 @@ __barkeep__ also has [python bindings](https://pypi.python.org/pypi/barkeep). +
+ +### Animations + +
+ - Display a waiting animation with a message: ```cpp @@ -61,6 +67,12 @@ __barkeep__ also has [python bindings](https://pypi.python.org/pypi/barkeep). +
+ +### Counters + +
+ - Display a counter to monitor a numeric variable while waiting: ```cpp @@ -82,6 +94,12 @@ __barkeep__ also has [python bindings](https://pypi.python.org/pypi/barkeep). +
+ +### Progress bars + +
+ - Display a progress bar to monitor a numeric variable and measure its completion by comparing against a total: ```cpp @@ -128,6 +146,12 @@ __barkeep__ also has [python bindings](https://pypi.python.org/pypi/barkeep). +
+ +### Deferred start + +
+ - Displaying can be deferred with `.show = false`, and explicitly invoked by calling `show()`, instead of at construction time. @@ -169,6 +193,12 @@ __barkeep__ also has [python bindings](https://pypi.python.org/pypi/barkeep). } ``` +
+ +### Iterable bar + +
+ - Automatically iterate over a container with a progress bar display (instead of monitoring an explicit progress variable): @@ -223,7 +253,47 @@ __barkeep__ also has [python bindings](https://pypi.python.org/pypi/barkeep). - + +
+ +### Functional progress + +
+ +- Use a function (e.g. lambda) to monitor progress, instead of a variable + (_credit: [jh0x](https://github.com/oir/barkeep/pull/97)_): + + ```cpp + unsigned long total_area = 10000; + unsigned long width = 0, height = 0; + auto bar = bk::ProgressBar([&] { return width * height; }, { + .total = total_area, + .message = "Sweeping area", + .speed = 1., + }); + while (width < 100 and height < 100) { + std::this_thread::sleep_for(70ms); + if (width < 100) { width++; } + if (height < 100) { height++; } + } + ``` + + Observe how a lambda is passed as the first argument as opposed to a variable + like `&width`. + + + + + + + + +
+ +### Multi display + +
+ - Combine diplays using `|` operator to monitor multiple variables: ```cpp @@ -259,6 +329,13 @@ __barkeep__ also has [python bindings](https://pypi.python.org/pypi/barkeep). Instead of using `|` operator, you can also call `Composite()` with the components explicitly, which also accepts an additional string argument as the delimiter between the components. See the example below. + +
+ +### Multiline + +
+ - If your display is multiline (has `\n` appear in it), all lines are automatically rerendered during animations. The example below combines three bars similarly to the example above, however uses `\n` as the delimiter: ```cpp @@ -303,6 +380,12 @@ __barkeep__ also has [python bindings](https://pypi.python.org/pypi/barkeep). +
+ +### Status messages + +
+ - Display status messages: ```cpp @@ -326,6 +409,12 @@ __barkeep__ also has [python bindings](https://pypi.python.org/pypi/barkeep). This is because a string is too big of an object to have unguarded concurrent access (see [this section](#caveat)). +
+ +### No-tty mode + +
+ - Use "no tty" mode to, e.g., output to log files: ```cpp diff --git a/docs/index.html b/docs/index.html index cd0731f..3361db4 100644 --- a/docs/index.html +++ b/docs/index.html @@ -173,6 +173,10 @@ monospace; font-style: italic; } + + .markdown-section ul { + margin-bottom: 0; + } diff --git a/docs/rec/lambda-dark.svg b/docs/rec/lambda-dark.svg new file mode 100644 index 0000000..3dbd6b1 --- /dev/null +++ b/docs/rec/lambda-dark.svg @@ -0,0 +1,140 @@ + + + + + + + + + + + + ~ ❯ ~ ❯ ./demo.out ~ ❯ ./demo.out ~ ❯ ./demo.out ~ ❯ ./demo.out ~ ❯ ./demo.out ~ ❯ ./demo.out Sweeping area 0.00% | | 0/10000 (0.00 it/s) Sweeping area 0.01% | | 1/10000 (9.51 it/s) Sweeping area 0.04% | | 4/10000 (29.23 it/s) Sweeping area 0.16% | | 16/10000 (114.10 it/s) Sweeping area 0.25% | | 25/10000 (89.22 it/s) Sweeping area 0.49% |▏ | 49/10000 (228.07 it/s) Sweeping area 0.64% |▏ | 64/10000 (142.98 it/s) Sweeping area 1.00% |▎ | 100/10000 (344.48 it/s) Sweeping area 1.21% |▎ | 121/10000 (202.59 it/s) Sweeping area 1.44% |▍ | 144/10000 (220.08 it/s) Sweeping area 1.96% |▌ | 196/10000 (509.01 it/s) Sweeping area 2.25% |▋ | 225/10000 (278.27 it/s) Sweeping area 2.89% |▊ | 289/10000 (630.88 it/s) Sweeping area 3.24% |▉ | 324/10000 (332.73 it/s) Sweeping area 3.61% |█ | 361/10000 (351.66 it/s) Sweeping area 4.41% |█▎ | 441/10000 (764.38 it/s) Sweeping area 4.84% |█▍ | 484/10000 (412.26 it/s) Sweeping area 5.76% |█▋ | 576/10000 (905.79 it/s) Sweeping area 6.25% |█▉ | 625/10000 (466.14 it/s) Sweeping area 6.76% |██ | 676/10000 (484.99 it/s) Sweeping area 7.84% |██▎ | 784/10000 (1030.01 it/s) Sweeping area 8.41% |██▌ | 841/10000 (541.93 it/s) Sweeping area 9.61% |██▉ | 961/10000 (1140.83 it/s) Sweeping area 10.24% |███ | 1024/10000 (617.88 it/s) Sweeping area 10.89% |███▎ | 1089/10000 (623.05 it/s) Sweeping area 12.25% |███▋ | 1225/10000 (1293.06 it/s) Sweeping area 12.96% |███▉ | 1296/10000 (675.14 it/s) Sweeping area 14.44% |████▎ | 1444/10000 (1452.18 it/s) Sweeping area 15.21% |████▌ | 1521/10000 (737.42 it/s) Sweeping area 16.00% |████▊ | 1600/10000 (750.67 it/s) Sweeping area 17.64% |█████▎ | 1764/10000 (1591.33 it/s) Sweeping area 18.49% |█████▌ | 1849/10000 (808.17 it/s) Sweeping area 20.25% |██████ | 2025/10000 (1672.79 it/s) Sweeping area 21.16% |██████▎ | 2116/10000 (865.08 it/s) Sweeping area 23.04% |██████▉ | 2304/10000 (1795.15 it/s) Sweeping area 24.01% |███████▏ | 2401/10000 (925.50 it/s) Sweeping area 25.00% |███████▌ | 2500/10000 (984.09 it/s) Sweeping area 27.04% |████████ | 2704/10000 (1994.43 it/s) Sweeping area 28.09% |████████▍ | 2809/10000 (1044.77 it/s) Sweeping area 29.16% |████████▋ | 2916/10000 (1017.66 it/s) Sweeping area 31.36% |█████████▍ | 3136/10000 (2119.87 it/s) Sweeping area 32.49% |█████████▋ | 3249/10000 (1115.13 it/s) Sweeping area 34.81% |██████████▍ | 3481/10000 (2254.42 it/s) Sweeping area 36.00% |██████████▊ | 3600/10000 (1131.48 it/s) Sweeping area 37.21% |███████████▏ | 3721/10000 (1172.91 it/s) Sweeping area 39.69% |███████████▉ | 3969/10000 (2430.32 it/s) Sweeping area 40.96% |████████████▎ | 4096/10000 (1220.92 it/s) Sweeping area 43.56% |█████████████ | 4356/10000 (2471.78 it/s) Sweeping area 44.89% |█████████████▍ | 4489/10000 (1264.46 it/s) Sweeping area 46.24% |█████████████▊ | 4624/10000 (1290.16 it/s) Sweeping area 49.00% |██████████████▋ | 4900/10000 (2624.51 it/s) Sweeping area 50.41% |███████████████ | 5041/10000 (1340.50 it/s) Sweeping area 53.29% |███████████████▉ | 5329/10000 (2737.88 it/s) Sweeping area 54.76% |████████████████▍ | 5476/10000 (1397.64 it/s) Sweeping area 57.76% |█████████████████▎ | 5776/10000 (2863.65 it/s) Sweeping area 59.29% |█████████████████▊ | 5929/10000 (1455.48 it/s) Sweeping area 60.84% |██████████████████▎ | 6084/10000 (1523.12 it/s) Sweeping area 64.00% |███████████████████▏ | 6400/10000 (3004.20 it/s) Sweeping area 65.61% |███████████████████▋ | 6561/10000 (1583.46 it/s) Sweeping area 68.89% |████████████████████▋ | 6889/10000 (3169.44 it/s) Sweeping area 70.56% |█████████████████████▏ | 7056/10000 (1588.08 it/s) Sweeping area 72.25% |█████████████████████▋ | 7225/10000 (1606.01 it/s) Sweeping area 75.69% |██████████████████████▋ | 7569/10000 (3286.57 it/s) Sweeping area 77.44% |███████████████████████▏ | 7744/10000 (1733.81 it/s) Sweeping area 81.00% |████████████████████████▎ | 8100/10000 (3385.70 it/s) Sweeping area 82.81% |████████████████████████▊ | 8281/10000 (1721.09 it/s) Sweeping area 84.64% |█████████████████████████▍ | 8464/10000 (1739.99 it/s) Sweeping area 88.36% |██████████████████████████▌ | 8836/10000 (3551.13 it/s) Sweeping area 90.25% |███████████████████████████ | 9025/10000 (1809.10 it/s) Sweeping area 94.09% |████████████████████████████▏ | 9409/10000 (3698.08 it/s) Sweeping area 96.04% |████████████████████████████▊ | 9604/10000 (1901.27 it/s) Sweeping area 100.00% |██████████████████████████████| 10000/10000 (0.00 it/s) ~ ❯ + \ No newline at end of file diff --git a/docs/rec/lambda-light.svg b/docs/rec/lambda-light.svg new file mode 100644 index 0000000..5435f15 --- /dev/null +++ b/docs/rec/lambda-light.svg @@ -0,0 +1,140 @@ + + + + + + + + + + + + ~ ❯ ~ ❯ ./demo.out ~ ❯ ./demo.out ~ ❯ ./demo.out ~ ❯ ./demo.out ~ ❯ ./demo.out ~ ❯ ./demo.out Sweeping area 0.00% | | 0/10000 (0.00 it/s) Sweeping area 0.01% | | 1/10000 (9.51 it/s) Sweeping area 0.04% | | 4/10000 (29.23 it/s) Sweeping area 0.16% | | 16/10000 (114.10 it/s) Sweeping area 0.25% | | 25/10000 (89.22 it/s) Sweeping area 0.49% |▏ | 49/10000 (228.07 it/s) Sweeping area 0.64% |▏ | 64/10000 (142.98 it/s) Sweeping area 1.00% |▎ | 100/10000 (344.48 it/s) Sweeping area 1.21% |▎ | 121/10000 (202.59 it/s) Sweeping area 1.44% |▍ | 144/10000 (220.08 it/s) Sweeping area 1.96% |▌ | 196/10000 (509.01 it/s) Sweeping area 2.25% |▋ | 225/10000 (278.27 it/s) Sweeping area 2.89% |▊ | 289/10000 (630.88 it/s) Sweeping area 3.24% |▉ | 324/10000 (332.73 it/s) Sweeping area 3.61% |█ | 361/10000 (351.66 it/s) Sweeping area 4.41% |█▎ | 441/10000 (764.38 it/s) Sweeping area 4.84% |█▍ | 484/10000 (412.26 it/s) Sweeping area 5.76% |█▋ | 576/10000 (905.79 it/s) Sweeping area 6.25% |█▉ | 625/10000 (466.14 it/s) Sweeping area 6.76% |██ | 676/10000 (484.99 it/s) Sweeping area 7.84% |██▎ | 784/10000 (1030.01 it/s) Sweeping area 8.41% |██▌ | 841/10000 (541.93 it/s) Sweeping area 9.61% |██▉ | 961/10000 (1140.83 it/s) Sweeping area 10.24% |███ | 1024/10000 (617.88 it/s) Sweeping area 10.89% |███▎ | 1089/10000 (623.05 it/s) Sweeping area 12.25% |███▋ | 1225/10000 (1293.06 it/s) Sweeping area 12.96% |███▉ | 1296/10000 (675.14 it/s) Sweeping area 14.44% |████▎ | 1444/10000 (1452.18 it/s) Sweeping area 15.21% |████▌ | 1521/10000 (737.42 it/s) Sweeping area 16.00% |████▊ | 1600/10000 (750.67 it/s) Sweeping area 17.64% |█████▎ | 1764/10000 (1591.33 it/s) Sweeping area 18.49% |█████▌ | 1849/10000 (808.17 it/s) Sweeping area 20.25% |██████ | 2025/10000 (1672.79 it/s) Sweeping area 21.16% |██████▎ | 2116/10000 (865.08 it/s) Sweeping area 23.04% |██████▉ | 2304/10000 (1795.15 it/s) Sweeping area 24.01% |███████▏ | 2401/10000 (925.50 it/s) Sweeping area 25.00% |███████▌ | 2500/10000 (984.09 it/s) Sweeping area 27.04% |████████ | 2704/10000 (1994.43 it/s) Sweeping area 28.09% |████████▍ | 2809/10000 (1044.77 it/s) Sweeping area 29.16% |████████▋ | 2916/10000 (1017.66 it/s) Sweeping area 31.36% |█████████▍ | 3136/10000 (2119.87 it/s) Sweeping area 32.49% |█████████▋ | 3249/10000 (1115.13 it/s) Sweeping area 34.81% |██████████▍ | 3481/10000 (2254.42 it/s) Sweeping area 36.00% |██████████▊ | 3600/10000 (1131.48 it/s) Sweeping area 37.21% |███████████▏ | 3721/10000 (1172.91 it/s) Sweeping area 39.69% |███████████▉ | 3969/10000 (2430.32 it/s) Sweeping area 40.96% |████████████▎ | 4096/10000 (1220.92 it/s) Sweeping area 43.56% |█████████████ | 4356/10000 (2471.78 it/s) Sweeping area 44.89% |█████████████▍ | 4489/10000 (1264.46 it/s) Sweeping area 46.24% |█████████████▊ | 4624/10000 (1290.16 it/s) Sweeping area 49.00% |██████████████▋ | 4900/10000 (2624.51 it/s) Sweeping area 50.41% |███████████████ | 5041/10000 (1340.50 it/s) Sweeping area 53.29% |███████████████▉ | 5329/10000 (2737.88 it/s) Sweeping area 54.76% |████████████████▍ | 5476/10000 (1397.64 it/s) Sweeping area 57.76% |█████████████████▎ | 5776/10000 (2863.65 it/s) Sweeping area 59.29% |█████████████████▊ | 5929/10000 (1455.48 it/s) Sweeping area 60.84% |██████████████████▎ | 6084/10000 (1523.12 it/s) Sweeping area 64.00% |███████████████████▏ | 6400/10000 (3004.20 it/s) Sweeping area 65.61% |███████████████████▋ | 6561/10000 (1583.46 it/s) Sweeping area 68.89% |████████████████████▋ | 6889/10000 (3169.44 it/s) Sweeping area 70.56% |█████████████████████▏ | 7056/10000 (1588.08 it/s) Sweeping area 72.25% |█████████████████████▋ | 7225/10000 (1606.01 it/s) Sweeping area 75.69% |██████████████████████▋ | 7569/10000 (3286.57 it/s) Sweeping area 77.44% |███████████████████████▏ | 7744/10000 (1733.81 it/s) Sweeping area 81.00% |████████████████████████▎ | 8100/10000 (3385.70 it/s) Sweeping area 82.81% |████████████████████████▊ | 8281/10000 (1721.09 it/s) Sweeping area 84.64% |█████████████████████████▍ | 8464/10000 (1739.99 it/s) Sweeping area 88.36% |██████████████████████████▌ | 8836/10000 (3551.13 it/s) Sweeping area 90.25% |███████████████████████████ | 9025/10000 (1809.10 it/s) Sweeping area 94.09% |████████████████████████████▏ | 9409/10000 (3698.08 it/s) Sweeping area 96.04% |████████████████████████████▊ | 9604/10000 (1901.27 it/s) Sweeping area 100.00% |██████████████████████████████| 10000/10000 (0.00 it/s) ~ ❯ + \ No newline at end of file From 0d370910850eaa9c62a6b6e97c58ae56fa39f1e7 Mon Sep 17 00:00:00 2001 From: oir Date: Sun, 5 Jan 2025 16:25:06 -0500 Subject: [PATCH 2/4] Add note to README --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 2f92f27..3f33c52 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ __barkeep__ strives to be [non-intrusive](#non-intrusive-design). +💡 _[Documentation](https://oir.github.io/barkeep/) is a superset of what's below and easier to navigate._ --- From 04e04ceaa0e7225fb4e66205ac081e747a6c1ad8 Mon Sep 17 00:00:00 2001 From: oir Date: Sun, 5 Jan 2025 16:29:54 -0500 Subject: [PATCH 3/4] Note caveat --- README.md | 3 +++ docs/README.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/README.md b/README.md index 3f33c52..3edfdce 100644 --- a/README.md +++ b/README.md @@ -258,6 +258,9 @@ __barkeep__ strives to be [non-intrusive](#non-intrusive-design). + Such monitoring functions are concurrently invoked, + see [this section](#Caveat) for what that might imply. + - Combine diplays using `|` operator to monitor multiple variables: ```cpp diff --git a/docs/README.md b/docs/README.md index f548867..2a47085 100644 --- a/docs/README.md +++ b/docs/README.md @@ -287,6 +287,9 @@ __barkeep__ also has [python bindings](https://pypi.python.org/pypi/barkeep). + Such monitoring functions are concurrently invoked, + see [this section](#caveat) for what that might imply. +
From 66f9f2b57691b233363a448264d9856479fd0f64 Mon Sep 17 00:00:00 2001 From: oir Date: Sun, 5 Jan 2025 16:31:00 -0500 Subject: [PATCH 4/4] . --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 3edfdce..e3e1d98 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ __barkeep__ strives to be [non-intrusive](#non-intrusive-design).
+ 💡 _[Documentation](https://oir.github.io/barkeep/) is a superset of what's below and easier to navigate._ ---