README

Rah_runtime returns runtimes from point A to B in microseconds. The plugin can be used to diagnose runtimes of specific blocks of Textpattern’s markup code.

Basics

<txp:rah_runtime format="1">
    ...contained statements...
</txp:rah_runtime>

The plugin introduces a new Textpattern tag, <txp:rah_runtime />. The tag calculates execution runtimes for Textpattern template markuThe runtimes can be printed to the page template and are added to a tag trace.

The rah_runtime tag can be used both as a container and as a self-closing single tag. When the tag is used as a container, it calculates a runtime of the wrapped code. When used as a self-closing single tag, it calculates a runtime from the first tag instance to the second.

Attributes

<txp:rah_runtime/> tag’s attributes are as follows.

return
If set to 1, the tag outputs the runtime to the page template. If 0 the runtime is only added and visible in the page’s tag trace when the site is in debugging mode. By default return is 0, and the runtimes are only added to the tag trace.
Example: return="1" Default: "0"

format
Return formatted version of the time. When used, resulting value (float) is presented as a fixed decimal number. By default the option is used (1).
Example: format="0" Default: "1"

index
With this attribute you can nest several tag pairs and count several independent runtimes. The index attribute only applies when <txp:rah_runtime /> is used as a self-closing single tag.
Example: index="articles" Default: "default"

persistent
If set to 1, the runtime is kept alive after returning. Normally the runtime pair is destroyed after using it, but with persistent the initial runtime is kept and still usable. The attribute is useful if you want to calculate multiple runtimes from same single starting point. The persistent attribute only applies when <txp:rah_runtime /> is used as a self-closing single tag.
Example: persistent="1" Default: "0"

Examples

Using as a container

As a container, rah_runtime calculates a runtime for the wrapped content.

<txp:rah_runtime>
    <txp:article_custom />
</txp:rah_runtime>

The above will return the contained statement’s results, as it would normally without the rah_runtime, and the runtime of the contained statement is added to the page’s tag trace. The tag trace should display a line similar to this:

[rah_runtime (default): 0.000010013580322]

Using as a single tag

When the rah_runtime tag is used as a single, self-closing tag, the runtime is calculated from a <txp:rah_runtime/> tag instance to the next. Essentially the runtime is for the markup and code between two <txp:rah_runtime/> tags.

<txp:rah_runtime />
    <!--
        Some code here, for example:
        <txp:article />
    -->
<txp:rah_runtime />

The above will return all the markup normally, like there weren’t any traces of rah_runtime, and the runtime is added to the page’s tag trace as a line similar to this:

[rah_runtime (default): 0.000010013580322]

Returning runtimes to the page

Normally the resulting runtimes are added to the tag trace and are not visible in the normal page content. That is unless return attribute is set to 1.

<txp:rah_runtime />
Runtime: <txp:rah_runtime return="1" />

The runtime is added to the tag trace and the above will return:

Runtime: 0.00021401458032

Using multiple nested tag pairs

The rah_runtime tag’s index attribute can be used to nest and mix multiple <txp:rah_runtime/> tags and runtime pairs together. This will allow calculating simultaneous runtimes that overlap each others.

<txp:rah_runtime index="2" />
<txp:rah_runtime index="1" />
Time1: <txp:rah_runtime index="1" return="1" />
Time2: <txp:rah_runtime index="2" return="1" />

The above will return two runtimes:

Time1: 0.000081
Time2: 0.000184

The time2 contains the runtime of time1 and more.

Using persistent runtimes

Persistent runtimes are useful when several runtimes are to be calculated from a same starting point.

<!--
    Starting the runtime timer
-->

<txp:rah_runtime persistent="1" return="1" />


<!--
    Some code here, for example <txp:article /> ...
    then output a (first) runtime
-->

<txp:rah_runtime persistent="1" return="1" />

<!--
    Some more code here, for example
    <txp:output_form form="myform" />

    Output runtime, calculated
    from the same original starting point
-->

<txp:rah_runtime persistent="1" return="1" />

<!--
    Even some more code.
    Finally, return the final runtime still calculated 
    from the same original starting point.
-->

<txp:rah_runtime return="1" />

Note that every one of the rah_runtime tags (except for the last) has persistent attribute set to 1. If the tag doesn’t have it, then the runtime pair is destroyed after returning it. To finally destroy the runtime, set persistent to "0" (zero) or leave it undefined.

Changelog

Version 0.5.0 – upcoming

Updated: Help file.

Version 0.4 – 2012/07/12

Added: return attribute.
Added: Now the runtimes are added to the tag trace.
Added: Container tag mode support.
Changed: By default runtimes are only visible in a tag trace. Set return attribute to 1 (return="1") output runtimes to the page template.
Changed: Default index to default. This is to avoid potential type juggling side-effects.

Version 0.3 – 2011/08/19

Added: a new attribute persistent. Disables destroying of used runtime pairs.
Changed: Now stores the runtimes in a static variable instead of a global.

Version 0.2 – 2010/06/18

Fixed: now returns as float (compatible with pre-PHP5). Thank you for reporting, Andreas.

Version 0.1 – 2010/06/15

Initial release.

rah / rah_runtime

Maintainers

Details