ArborX

tprof

Longname: t prof iler   Open the Documentation Legend
Released: 7.69a 
Created: 7.69a 
See also: tformat

Summary
 This macro allows you to see which tags take the most time during formatting and therefore optimise templates for maximum efficiency.
Example (n/a)
 No example is available for this feature.

Syntax (7.69a)
tprof  mode:n?  tagname:s?
mode:n
-1  Enable profiling (manual).
0  Disable profiling (manual).
1  Automatic profiling of formatting during tformat
2  Automatic profiling of formatting during trf
3  Automatic profiling of formatting during tprint
10  Create report from collected data (manual).
11  Reset all collected data (manual).

Name of text tag to write report log (default="tproflog").
tagname:s

Name of text tag to write report log (default="tproflog").

Profiling consists of two basic things:

4 Produce a report.

The first step is top enable collection of the profiling data. For example a manual profiling operation. Manual profiling is a little more involved and very useful for scripting.

Ensure that all profiling data is reset with tprof 11 and then enable manual profiling with the macro tprof -1.

Next, format. Use the trf or tformat macros or even type some text into Arbortext APP's WYSIWYG area. Arbortext APP keeps two profiling statistics for each tag in your document:

4 The number of "ticks" spent formatting any descendant tags of the tag.

When Arbortext APP is formatting with profiling turned on, it periodically updates the profiling information. During the update, formatting is temporarily suspended to examine the current formatting stack and add the number of elapsed ticks since the last update to each tag in the stack. The period of a "tick" is important because the number of ticks for each tag will be displayed later in the profile log. The number of ticks in a second is given by the 01021 getvar. That is 1000 in Windows platforms.

Next, stop the profiling with the macro tprof 0 and then produce a report with the macro tprof 10. Finally, examine the log using the stream editor (easier to read and scrollable) ttagedit "tproflog".
Due to the minimally intrusive method of profiling, the results in the log should be considered as an accurate estimate rather than exact. If Arbortext APP formats a tag entirely between ticks then the tag has recorded a proportionate amount of time spent when compared to other tags. The important thing is that the tags that have taken most time will be at the top of the list.

The automatic profiling options greatly simplify the above procedure. It can be enabled during tformat (tprof1), trf (tprof 2) or tprint (tprof 3). When the appropriate macro is used, the starting, stopping and reporting is automatically done at appropriate times, leaving you to simply inspect the log (ttagedit "tproflog") before the next occurence of the macro overwrites it. Remember to switch off profiling (tprof 0) when you no longer need it as there is a small but significant overhead for it.

Document created on 08-Feb-2003 (revision 1)