profiler(3tcl)

💖 profiler — the Tcl source code profiler, but make it a bestie explaining it 💖

okay so bestie, gather round, because this is the manual page for profiler from tcllib, and it's genuinely one of the cutest little tools ever. it's a Tcl source code profiler. periodt. let's get into it. ✨

---

🌸 SYNOPSIS 🌸

like, here's the vibe, literally:

package require Tcl 8.5 9

package require profiler ?0.7?

::profiler::init

::profiler::dump pattern

::profiler::print ?pattern?

::profiler::reset ?pattern?

::profiler::suspend ?pattern?

::profiler::resume ?pattern?

::profiler::new-disabled

::profiler::new-enabled

::profiler::sortFunctions key

---

🦋 DESCRIPTION 🦋

so the profiler package gives you a simple Tcl source code profiler. and when i say simple i mean it's a function-level profiler — it collects only function-level info, NOT the more detailed line-level tea. so don't come for it asking for line-by-line receipts, that's not the vibe it's giving. 🙈

the way it works is honestly iconic: it operates by redefining the Tcl proc command. yeah. it just. takes over proc. main character energy fr fr.

and you kick the whole thing off with ::profiler::init. that's the moment. that's the slay. 💅

---

👑 COMMANDS 👑

::profiler::init

initiate profiling, bestie. every single procedure created after this command is called will be profiled. and if you wanna profile an entire application, this command has to be called before any other commands. like, before. no cap. it's giving "first in line or not at all".

::profiler::dump pattern

dump the profiling info for all the functions matching pattern. if you don't specify a pattern, you get info for all the functions back. no pressure.

the result is a list of key/value pairs that maps function names to info about that function. and the info about each function is, in turn, a list of key/value pairs. lists inside lists. nested. adorable. 🎀

the keys it uses and their values are:

• totalCalls — the total number of times functionName was called.
• callerDist — a list of key/value pairs mapping each calling function that called functionName to the number of times it called functionName.
• compileTime — the runtime, in clock clicks, of functionName the first time that it was called.
• totalRuntime — the sum of the runtimes of all calls of functionName.
• averageRuntime — average runtime of functionName.
• descendantTime — sum of the time spent in descendants of functionName.
• averageDescendantTime — average time spent in descendants of functionName.

::profiler::print ?pattern?

print profiling info for all functions matching pattern. no pattern? then info about all functions gets displayed. and the return result is a human readable display of the profiling information. it's giving readable. it's giving for the people. 🫶

::profiler::reset ?pattern?

reset profiling info for all functions matching pattern. and if no pattern is specified, info gets reset for all the functions. fresh start, clean slate, healing era. ✨

::profiler::suspend ?pattern?

suspend profiling for all functions matching pattern. no pattern? then profiling gets suspended for all functions. it stops gathering profiling information after this command is issued.

BUT. and this is important bestie — it does not erase any profiling information that was already gathered. your data is safe. it's just napping. 😴

use the resume command to re-enable profiling.

::profiler::resume ?pattern?

resume profiling for all functions matching pattern. no pattern? all functions get resumed. this is the command you invoke after suspending the profiler in the code. wake up babe, we're profiling again. 🌈

::profiler::new-disabled

change the initial profiling state for new procedures. invoking this command disables profiling for all procedures created after this command, until new-enabled is invoked. so everything new shows up unprofiled by default. you can still activate profiling of specific procedures via resume. 💜

::profiler::new-enabled

change the initial profiling state for new procedures. invoking this command enables profiling for all procedures created after this command, until new-disabled is invoked. so everything new shows up profiled by default. and if you want to keep specific procedures out of it, prevent profiling of them via suspend. 🧚

::profiler::sortFunctions key

return a list of functions sorted by a particular profiling statistic. the supported values for key are: calls, exclusiveTime, compileTime, nonCompileTime, totalRuntime, avgExclusiveTime, and avgRuntime.

the return result is a list of lists, where each sublist consists of a function name and the value of key for that function. lists of lists again. we love a consistent aesthetic. 💅

---

💀 BUGS, IDEAS, FEEDBACK 💀

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. like, that's just how it is. 😭

please report such in the category profiler of the Tcllib Trackers at [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 the ideas. we want them fr fr.

when proposing code changes, please provide unified diffs, i.e. the output of diff -u. that's the format. that's the assignment. 🔥

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. left-most button. secondary navigation bar. you got this. 🎀

---

⭐ KEYWORDS ⭐

performance, profile, speed

---

🍓 CATEGORY 🍓

Programming tools

---

and that's the whole page, bestie — brought to you by tcllib, version 0.7, and this little manual page is profiler(3tcl). go profile something and make it everyone's problem. slay. 💖✨🦋