Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-library-profiler.tex

raw
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}