bench_lang_spec(3tcl)

🌸 NAME

bench_lang_spec — it's giving bench language specification, bestie. 💖 Like, the whole entire spec. The manual it lives in is the Tcllib Documentation tools one, and yes she is a 3tcl page. 🎀

---

✨ SYNOPSIS

bench_rm path...

bench_tmpfile

bench options...

---

💅 DESCRIPTION

okay so this document specifies both the names and the syntax of every single command that together make up the bench language, version 1. ✨

And because this doc is meant to be an actual reference, the commands are listed in alphabetical order and the descriptions stay relatively short — no yapping, we're being efficient. If you're a beginner though? Go read the more informally written bench language introduction first, fr fr. 🫶

---

🛠️ COMMANDS

bench_rm path...

This one silently removes the files you handed it as arguments, and then it returns the empty string as its result. 💅

⚠️ okay so listen: this command is trusted. There is no checking whether the files you specified live outside of whatever restricted area the benchmarks are run in. She does not vibe check the paths. She just goes. 💀

bench_tmpfile

This returns the path to a bench-specific unique temporary file. 🌸 Unique meaning: multiple calls will hand you back different paths. And while that path may already exist from previous runs, the command itself does not create anything. 🙈

The base location of those temporary files is platform dependent:

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

bench options...

This declares a single benchmark. Its result is the empty string. All the parts of the benchmark get declared via options and their values, and the options can occur in any order. Iconic, honestly. 👑

The accepted options are:

• -body script — declares the body of the benchmark, aka the Tcl script whose performance we wish to measure. This option, and -desc, are the two required parts of each benchmark. ⭐
• -desc msg — declares the name of the benchmark. It has to be unique, or timing data from different benchmarks will get mixed together. 😭

🚨 Beware! This requirement is not checked when benchmarks are executed, and the system will silently produce bogus data. This option, and -body, are the two required parts of each benchmark.

• -ipost script — declares a script which is run immediately after each iteration of the body. Its job is to release resources created by the body, or -ipre-bodym which we do not wish to live into the next iteration. 🧚
• -ipre script — 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 — declares the maximum number of times to run the -body of the benchmark. During execution, this and the global maximum number of iterations get compared, and the smaller of the two values is the one that's used. This option should be used only for benchmarks which are expected or known to take a long time per run. I.e. reduce the number of times they're run, to keep the overall time for the execution of the whole benchmark within manageable limits. 🕐
• -post script — 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 -pre-body. 🎀
• -pre script — 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 in order to run without failing. 🌈

---

🐛 BUGS, IDEAS, FEEDBACK

This document, and the package it describes, will undoubtedly contain bugs and other problems. It's not a personal attack, it's just how docs are. 😭

Please report such in the category bench of the Tcllib Trackers: http://core.tcl.tk/tcllib/reportlist. And please also report any ideas for enhancements you may have for either the package and/or the documentation — we want them, fr fr. 🫶

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. Attachments can be made 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. iykyk.

---

👀 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!! 🌸 this one's tcllib, version 1.0, and it's bench_lang_spec(3tcl) — she ate and left no crumbs. 💅✨🎀