| 1 |
% Copyright 2019 by Christian Feuersaenger |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Profiler Library} |
| 12 |
|
| 13 |
{\noindent {\emph{by Christian Feuersänger}}} |
| 14 |
|
| 15 |
\begin{pgflibrary}{profiler} |
| 16 |
A library to simplify the optimization of runtime speed of \TeX\ programs. |
| 17 |
|
| 18 |
It relies on the |pdftex| primitive |
| 19 |
\declareandlabel{\pdfelapsedtime}\footnote{The primitive is emulated in |
| 20 |
lua\TeX.} to count (fractional) seconds and counts total time and self time |
| 21 |
for macro invocations. |
| 22 |
\end{pgflibrary} |
| 23 |
|
| 24 |
|
| 25 |
\subsection{Overview} |
| 26 |
|
| 27 |
The intended audience for this library are people writing \TeX\ code which |
| 28 |
should be optimized. It is certainly \emph{not} useful for the end-user. |
| 29 |
|
| 30 |
The work flow for the optimization is simple: the preamble contains |
| 31 |
configuration commands like |
| 32 |
% |
| 33 |
\begin{codeexample}[code only] |
| 34 |
\usepgflibrary{profiler} |
| 35 |
\pgfprofilenewforenvironment{tikzpicture} |
| 36 |
\pgfprofilenewforcommand{\pgfkeys}{1} |
| 37 |
\end{codeexample} |
| 38 |
% |
| 39 |
\noindent and then, the time between |\begin{tikzpicture}| and |
| 40 |
|\end{tikzpicture}| and the time required to call |\pgfkeys| will be collected. |
| 41 |
|
| 42 |
At the end, a short usage summary like |
| 43 |
% |
| 44 |
\begin{codeexample}[code only, tikz syntax=false] |
| 45 |
pgflibraryprofiler(main job) {total time=1.07378sec; (100.0122%) self time=0.034sec; (3.1662%)} |
| 46 |
pgflibraryprofiler(<ENV>tikzpicture) {total time=1.03978sec; (96.84601%) self time=1.00415sec; (93.52722%)} |
| 47 |
pgflibraryprofiler(<CS>pgfkeys) {total time=0.03563sec; (3.31726%) self time=0.03563sec; (3.31726%)} |
| 48 |
\end{codeexample} |
| 49 |
% |
| 50 |
\noindent will be provided in the log file, furthermore, the same information |
| 51 |
is available in a text table called |\jobname.profiler.|\meta{datetime}|.dat| |
| 52 |
which is of the form: |
| 53 |
% |
| 54 |
\begin{codeexample}[code only, tikz syntax=false] |
| 55 |
profilerentry totaltime[s] totaltime[percent] selftime[s] selftime[percent] |
| 56 |
main job 1.07378 100.0122 0.034 3.1662 |
| 57 |
<ENV>tikzpicture 1.03978 96.84601 1.00415 93.52722 |
| 58 |
<CS>pgfkeys 0.03563 3.31726 0.03563 3.31726 |
| 59 |
\end{codeexample} |
| 60 |
% |
| 61 |
Here, the |totaltime| means the time used for all invocations of the respective |
| 62 |
profiler entry (one row in the table). The |selftime| measures time which is |
| 63 |
not already counted for in another profiler entry which has been invoked within |
| 64 |
the current one. The example above is not very exciting: the main job consists |
| 65 |
only of several (quite complex) pictures and nothing else. Thus, its total time |
| 66 |
is large. However, the self time is very small because the |tikzpicture|s are |
| 67 |
counted separately, and they have been invoked within the |main job|. The |
| 68 |
|\pgfkeys| control sequence has been invoked within the |tikzpicture|, that's |
| 69 |
why the |selftime| for the |tikzpicture| is a little bit smaller than its |
| 70 |
|totaltime|. |
| 71 |
|
| 72 |
|
| 73 |
\subsection{Requirements} |
| 74 |
|
| 75 |
The library works with |pdftex| and |luatex|. Furthermore, it requires a more |
| 76 |
or less recent version of |pdftex| which supports the |\pdfelapsedtime| |
| 77 |
directive. |
| 78 |
|
| 79 |
|
| 80 |
\subsection{Defining Profiler Entries} |
| 81 |
|
| 82 |
Unlike profilers for C/C++ or java, this library doesn't extract information |
| 83 |
about every \TeX\ macro automatically, nor does it collect information for each |
| 84 |
of them. Instead, every profiler entry needs to be defined explicitly. Only |
| 85 |
defined profiler entries will be processed. |
| 86 |
|
| 87 |
\begin{command}{\pgfprofilenew\marg{name}} |
| 88 |
Defines a new profiler entry named \meta{name}. |
| 89 |
|
| 90 |
This updates a set of internal registers used to track the profiler entry. |
| 91 |
The \meta{name} can be arbitrary, it doesn't need to be related to any |
| 92 |
\TeX\ macro. |
| 93 |
|
| 94 |
The actual job of counting seconds is accomplished using |
| 95 |
|\pgfprofilestart|\marg{name} followed eventually by the command |
| 96 |
|\pgfprofileend|\marg{name}. |
| 97 |
|
| 98 |
It doesn't hurt if |\pgfprofilenew| is called multiple times with the same |
| 99 |
name. |
| 100 |
\end{command} |
| 101 |
|
| 102 |
\begin{command}{\pgfprofilenewforcommand\oarg{profiler entry name}\marg{\textbackslash macro}\marg{arguments}} |
| 103 |
Defines a new profiler entry which will measure the time spent in |
| 104 |
\meta{\textbackslash macro}. This calls |\pgfprofilenew| and replaces the |
| 105 |
current definition of \meta{\textbackslash macro} with a new one. |
| 106 |
|
| 107 |
If \oarg{profiler entry name} has been provided, this defines the argument |
| 108 |
for |\pgfprofilenew|. It is allowed to use the same name for multiple |
| 109 |
commands; in this case, they are treated as if it where the same command. |
| 110 |
If the optional argument is not used, the profiler entry will be called |
| 111 |
`\declareandlabel{\pgfprofilecs}\meta{macro}' (\meta{macro} without |
| 112 |
backslash) where |\pgfprofilecs| is predefined to be |<CS>|. |
| 113 |
|
| 114 |
The replacement macro will collect all required arguments, start counting, |
| 115 |
invoke the original macro definition and stop counting. |
| 116 |
|
| 117 |
The following macro types are supported within |\pgfprofilenewforcommand|: |
| 118 |
% |
| 119 |
\begin{itemize} |
| 120 |
\item commands which take one (optional) argument in square brackets |
| 121 |
followed by one optional argument which has to be delimited by |
| 122 |
curly braces (use an empty argument for \meta{arguments} in this |
| 123 |
case), |
| 124 |
\item commands which take one (optional) argument in square brackets |
| 125 |
and \emph{exactly} \meta{arguments} arguments afterwards. |
| 126 |
\end{itemize} |
| 127 |
|
| 128 |
Take a look at |\pgfprofilenewforcommandpattern| in case you have more |
| 129 |
complicated commands. |
| 130 |
|
| 131 |
Note that the library can't detect if a command has been redefined |
| 132 |
somewhere. |
| 133 |
\end{command} |
| 134 |
|
| 135 |
\begin{command}{\pgfprofilenewforcommandpattern\oarg{profiler entry name}\marg{\textbackslash macro}\marg{argument pattern}\marg{invocation pattern}} |
| 136 |
A variant of |\pgfprofilenewforcommand| which can be used with arbitrary |
| 137 |
\meta{argument patterns}. Example: |
| 138 |
% |
| 139 |
\begin{codeexample}[code only] |
| 140 |
\def\mymacro#1\to#2\in#3{ ... } |
| 141 |
\pgfprofilenewforcommandpattern{\mymacro}{#1\to#2\in#3}{{#1}\to{#2}\in{#3}} |
| 142 |
\end{codeexample} |
| 143 |
|
| 144 |
Note that |\pgfprofilenewforcommand| is a special case of |
| 145 |
|\pgfprofilenewforcommandpattern|: |
| 146 |
% |
| 147 |
\begin{codeexample}[code only] |
| 148 |
\def\mymacro#1#2{ ... } |
| 149 |
\pgfprofilenewforcommand\macro{2} |
| 150 |
\pgfprofilenewforcommandpattern{\mymacro}{#1#2}{{#1}{#2}} |
| 151 |
\end{codeexample} |
| 152 |
% |
| 153 |
Thus, \meta{argument pattern} is a copy-paste from the definition of your |
| 154 |
command. The \meta{invocation pattern} is used by the |profiler| library to |
| 155 |
invoke the \emph{original} command, so it is closely related to |
| 156 |
\meta{argument pattern}, but it needs extra curly braces around each |
| 157 |
argument. |
| 158 |
|
| 159 |
The behavior of |\pgfprofilenewforcommandpattern| is the same as discussed |
| 160 |
above: it defines a new profiler entry which will measure the time spent in |
| 161 |
\meta{\textbackslash macro}. The details about this definition has already |
| 162 |
been described. Note that up to one optional argument in square brackets is |
| 163 |
also checked automatically. |
| 164 |
|
| 165 |
If you like to profile a command which doesn't match here for whatever |
| 166 |
reasons, you'll have to redefine it manually and insert |\pgfprofilestart| |
| 167 |
and |\pgfprofileend| in appropriate places. |
| 168 |
\end{command} |
| 169 |
|
| 170 |
\begin{command}{\pgfprofileshowinvocationsfor\marg{profiler entry name}} |
| 171 |
Enables verbose output for \emph{every} invocation of \meta{profiler entry |
| 172 |
name}. |
| 173 |
|
| 174 |
This is only available for profiler entries for commands (those created by |
| 175 |
|\pgfprofilenewforcommand| for example). It will also show all given |
| 176 |
arguments. |
| 177 |
\end{command} |
| 178 |
|
| 179 |
\begin{command}{\pgfprofileshowinvocationsexpandedfor\marg{profiler entry name}} |
| 180 |
A variant of |\pgfprofileshowinvocationsfor| which will expand all |
| 181 |
arguments for \meta{profiler entry name} before showing them. The |
| 182 |
invocation as such is not affected by this expansion. |
| 183 |
|
| 184 |
This expansion (with |\edef|) might yield unrecoverable errors for some |
| 185 |
commands. Handle with care. |
| 186 |
\end{command} |
| 187 |
|
| 188 |
\begin{command}{\pgfprofilenewforenvironment\oarg{profiler entry name}\marg{environment name}} |
| 189 |
Defines a new profiler entry which measures time spent in the environment |
| 190 |
\meta{environment name}. |
| 191 |
|
| 192 |
This calls |\pgfprofilenew| and handles the begin/end of the environment |
| 193 |
automatically. |
| 194 |
|
| 195 |
The argument for |\pgfprofilenew| is \meta{profiler entry name}, or, if |
| 196 |
this optional argument is not used, it is |
| 197 |
`\declareandlabel{\pgfprofileenv}\meta{environment name}' where |
| 198 |
|\pgfprofileenv| is predefined as |<ENV>|. Again, it is permitted to use |
| 199 |
the same \meta{profiler entry name} multiple times to merge different |
| 200 |
commands into one output section. |
| 201 |
\end{command} |
| 202 |
|
| 203 |
\begin{command}{\pgfprofilestart\marg{profiler entry name}} |
| 204 |
Starts (or resumes) timing of \meta{profiler entry name}. The argument must |
| 205 |
have been declared in the preamble using |\pgfprofilenew|. |
| 206 |
|
| 207 |
Nested calls of |\pgfprofilestart| with the same argument will be ignored. |
| 208 |
|
| 209 |
The invocation of this command doesn't change the environment: it doesn't |
| 210 |
introduce any \TeX\ groups nor does it modify the token list. |
| 211 |
\end{command} |
| 212 |
|
| 213 |
\begin{command}{\pgfprofileend\marg{profiler entry name}} |
| 214 |
Stops (or interrupts) timing of \meta{profiler entry name}. |
| 215 |
|
| 216 |
This command finishes a preceding call to |\pgfprofilestart|. |
| 217 |
\end{command} |
| 218 |
|
| 219 |
\begin{command}{\pgfprofilepostprocess} |
| 220 |
For \LaTeX, this command is installed automatically in |\end{document}|. It |
| 221 |
stops all running timings, evaluates them and returns the result into the |
| 222 |
logfile. Furthermore, it generates a text table called |
| 223 |
|\jobname.profiler.|\meta{YYYY}|-|\meta{MM}|-|\meta{DD}|_|\meta{HH}|h_|\meta{MM}|m.dat| |
| 224 |
with the same information. |
| 225 |
|
| 226 |
Note that the |profiler| library predefines two profiler entries, namely |
| 227 |
|main job| which counts time from the beginning of the document until |
| 228 |
|\pgfprofilepostprocess| and |preamble| which counts time from the |
| 229 |
beginning of the document until |\begin{document}|. |
| 230 |
\end{command} |
| 231 |
|
| 232 |
\begin{command}{\pgfprofilesetrel\marg{profiler entry name} (initially main job)} |
| 233 |
Sets the profiler entry whose total time will be used to compute all other |
| 234 |
relative times. Thus, \meta{profiler entry name} will use $100\%$ of the |
| 235 |
total time per definition, all other relative times are relative to this |
| 236 |
one. |
| 237 |
\end{command} |
| 238 |
|
| 239 |
\begin{command}{\pgfprofileifisrunning\marg{profiler entry name}\marg{true code}\marg{false code}} |
| 240 |
Invokes \marg{true code} if \marg{profiler entry name} is currently running |
| 241 |
and \marg{false code} otherwise. |
| 242 |
\end{command} |