bench_lang_spec(n)

okay bestie, pull up a chair 🫶 this is bench_lang_spec(n), the whole entire tea on the bench language. grab a strawberry 🍓, we're getting into it.

---

✨ NAME ✨

• bench_lang_spec — the bench language specification 💖

🌸 SYNOPSIS 🌸

bench_rm path...

bench_tmpfile

bench options...

🦋 DESCRIPTION 🦋

This doc is the full spec of both the names and the syntax of every single command that together make up the bench language, version 1. It's a reference, so the commands are listed in alphabetical order and the descriptions are pretty short on purpose — no fluff, just facts. ✨

If you're a beginner tho? Go read the more informally written bench language introduction first, fr fr. This one is not the vibe for learning, it's the vibe for looking stuff up. 💅

---

👑 COMMANDS 👑

bench_rm path...

This one silently removes the files you hand it as arguments, then returns the empty string as its result. That's it, that's the whole command. 😌

⚠️ bestie, listen: this command is trusted. There is no checking whether the files you named are outside of whatever restricted area the benchmarks are run in. It just does the thing. Be normal about it. 💀

bench_tmpfile

Returns the path to a bench-specific unique temporary file. Unique means multiple calls give you different paths — no repeats, periodt. And heads up: while the path may exist from previous runs, the command itself does not create anything. It's just handing you a name. 🙈

The base location of the temporary files is platform dependent:

• Unix, and indeterminate platform — "/tmp"
• Windows — $TEMP
• Anything else — the current working directory.

bench options...

This command declares a single benchmark. 🎀 Its result is the empty string. Every part of the benchmark gets declared through options and their values, and the options can show up in any order — no strict sequencing, we're chill like that.

The accepted options are:

• -body script — the argument declares the body of the benchmark, i.e. the Tcl script whose performance we want to measure. This option, together with -desc, is one of the two required parts of each benchmark. 👑
• -desc msg — the argument declares the name of the benchmark. It has to be unique, otherwise timing data from different benchmarks gets mixed together. This option, together with -body, is one of the two required parts of each benchmark.

😭 BEWARE! This uniqueness requirement is not checked when benchmarks are executed, and the system will silently produce bogus data. Not a drill. Nothing will yell at you. You'll just have wrong numbers and no idea why.

• -ipost script — the argument declares a script which is run immediately after each iteration of the body. Its job is to release resources created by the body, or by -ipre-bodym, that we don't want living on into the next iteration. 🧹
• -ipre script — the argument declares a script which is run immediately before each iteration of the body. Its job is to create the state of the system that the body expects, so that we actually measure the right thing. 🎯
• -iterations num — the argument declares the maximum number of times to run the -body of the benchmark. During execution, this value and the global maximum number of iterations are compared, and the smaller of the two is the one that gets used.

This option should only be used for benchmarks which are expected or known to take a long time per run. Like — reduce the number of times they run so the overall time for executing the whole benchmark stays within manageable limits. ⏳

• -post script — the argument declares a script which is run after all iterations of the body have been run. Its job is to release resources created by the body, or by -pre-body. 🧼
• -pre script — the argument declares a script which is run before any of the iterations of the body are run. Its job is to create whatever resources the body needs so it can run without failing. 🛠️

---

😭 BUGS, IDEAS, FEEDBACK 😭

This document, and the package it describes, will undoubtedly contain bugs and other problems. Like, obviously. Please report those in the category bench of the Tcllib Trackers: http://core.tcl.tk/tcllib/reportlist. 🙏

Also please report any ideas for enhancements you may have for either the package and/or the documentation — we want them, we love them, send them. ✨

When proposing code changes, please provide unified diffs, i.e. the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. You can make an attachment by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. 👑

---

🎀 SEE ALSO 🎀

• bench_intro
• bench_lang_intro

🔥 KEYWORDS 🔥

• bench language
• benchmark
• performance
• specification
• testing

🌈 CATEGORY 🌈

Benchmark tools

💜 COPYRIGHT 💜

Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

and that's the whole page bestie, you ate that 💅 this came to you courtesy of tcllib, version 1.0 — go forth and benchmark responsibly, ily 🫶🌸