Difference between revisions of "Profiling Module"
Jump to navigation
Jump to search
m (Text replacement - "'''Signatures'''" to "'''Signature'''") |
|||
Line 11: | Line 11: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
|<pre>prof:track( | |<pre>prof:track( | ||
$expression as item() | $expression as item() | ||
Line 51: | Line 51: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
|<pre>prof:time( | |<pre>prof:time( | ||
$expr as item() | $expr as item() | ||
Line 72: | Line 72: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
|<pre>prof:memory( | |<pre>prof:memory( | ||
$expr as item() | $expr as item() | ||
Line 93: | Line 93: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
|<pre>prof:current-ms() as xs:integer</pre> | |<pre>prof:current-ms() as xs:integer</pre> | ||
|- valign="top" | |- valign="top" | ||
Line 111: | Line 111: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
|<pre>prof:current-ns() as xs:integer</pre> | |<pre>prof:current-ns() as xs:integer</pre> | ||
|- valign="top" | |- valign="top" | ||
Line 140: | Line 140: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
|<pre>prof:dump( | |<pre>prof:dump( | ||
$expr as item()* | $expr as item()* | ||
Line 157: | Line 157: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
|<pre>prof:variables() as empty-sequence()</pre> | |<pre>prof:variables() as empty-sequence()</pre> | ||
|- valign="top" | |- valign="top" | ||
Line 175: | Line 175: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
|<pre>prof:type( | |<pre>prof:type( | ||
$expr as item()* | $expr as item()* | ||
Line 188: | Line 188: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
|<pre>prof:gc( | |<pre>prof:gc( | ||
$count as xs:integer := () | $count as xs:integer := () | ||
Line 201: | Line 201: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
|<pre>prof:runtime( | |<pre>prof:runtime( | ||
$name of xs:string as | $name of xs:string as | ||
Line 227: | Line 227: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
|<pre>prof:void( | |<pre>prof:void( | ||
$value as item()* | $value as item()* | ||
Line 247: | Line 247: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
|<pre>prof:sleep( | |<pre>prof:sleep( | ||
$ms as xs:integer | $ms as xs:integer | ||
Line 263: | Line 263: | ||
{| width='100%' | {| width='100%' | ||
|- valign="top" | |- valign="top" | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
|<pre>prof:human( | |<pre>prof:human( | ||
$number as xs:integer | $number as xs:integer |
Revision as of 15:04, 9 March 2023
This XQuery Module contains various functions to test and profile code, and to dump information to standard output.
Contents
Conventions
All functions and errors in this module are assigned to the http://basex.org/modules/prof
namespace, which is statically bound to the prof
prefix.
Performance Functions
prof:track
Signature | prof:track( $expression as item() $options as map(*)? := () ) as item()* |
Summary | Measures the execution time and memory consumption required for evaluating the specified $expression and returns a map with the results. The following $options are available:
Helpful notes:
|
Properties | The function is non-deterministic: evaluation order will be preserved by the compiler. |
Examples |
<syntaxhighlight lang="xquery"> prof:track(fetch:doc('factbook.xml'))?memory => prof:human() </syntaxhighlight>
<syntaxhighlight lang="xquery"> map { "memory": 21548400, "value": (2, 4, 6, 8, 10, ...) } </syntaxhighlight> |
prof:time
Signature | prof:time( $expr as item() $label as xs:string := () ) as item()* |
Summary | Measures the time needed to evaluate $expr and outputs a string to standard error or, if the GUI is used, to the Info View. An optional $label may be specified to tag the profiling result. See prof:track for further notes.
|
Properties | The function is non-deterministic: evaluation order will be preserved by the compiler. |
Examples |
|
prof:memory
Signature | prof:memory( $expr as item() $label as xs:string := () ) as item()* |
Summary | Measures the memory allocated by evaluating $expr and outputs a string to standard error or, if the GUI is used, to the Info View. An optional $label may be specified to tag the profiling result. See prof:track for further notes.
|
Properties | The function is non-deterministic: evaluation order will be preserved by the compiler. |
Examples |
|
prof:current-ms
Signature | prof:current-ms() as xs:integer |
Summary | Returns the number of milliseconds passed since 1970/01/01 UTC. The granularity of the value depends on the underlying operating system and may be larger. For example, many operating systems measure time in units of tens of milliseconds. |
Properties | In contrast to fn:current-time() , the function is non-deterministic and returns different values every time it is called. Its evaluation order will be preserved by the compiler.
|
Examples |
|
prof:current-ns
Signature | prof:current-ns() as xs:integer |
Summary | Returns the current value of the most precise available system timer in nanoseconds. |
Properties | In contrast to fn:current-time() , the function is non-deterministic and returns different values every time it is called. Its evaluation order will be preserved by the compiler.
|
Examples | Measures the time of an expression:
<syntaxhighlight lang="xquery"> let $ns1 := prof:current-ns() return ( (: process to measure :) (1 to 1000000)[. = 0], let $ns2 := prof:current-ns() let $ms := ((($ns2 - $ns1) idiv 10000) div 100) return $ms || ' ms' ) </syntaxhighlight> |
Debugging Functions
prof:dump
Signature | prof:dump( $expr as item()* $label as xs:string := () ) as empty-sequence() |
Summary | Dumps a serialized representation of $expr to STDERR , optionally prefixed with $label , and returns an empty sequence. If the GUI is used, the dumped result is shown in the Info View.
|
Properties | In contrast to fn:trace() , the consumed expression will not be passed on.
|
prof:variables
Signature | prof:variables() as empty-sequence() |
Summary | Prints a list of all current local and global variable assignments to standard error or, if the GUI is used, to the Info View. As every query is optimized before being evaluated, not all of the original variables may be visible in the output. Moreover, many variables of function calls will disappear because functions are inlined. Function inlining can be turned off by setting INLINELIMIT to 0 .
|
Properties | The function is non-deterministic: evaluation order will be preserved by the compiler. |
Examples |
|
prof:type
Signature | prof:type( $expr as item()* ) as item()* |
Summary | Similar to fn:trace($expr, $msg) , but instead of a user-defined message, it emits the compile-time type and estimated result size of its argument.
|
prof:gc
Signature | prof:gc( $count as xs:integer := () ) as empty-sequence() |
Summary | Enforces Java garbage collection. If no $count is supplied, garbage will be collected once. Please note that this function should only be used for debugging purposes; in productive code, it is best to trust the garbage collecting strategies of Java.
|
prof:runtime
Signature | prof:runtime( $name of xs:string as ) as xs:integer |
Summary | Returns the value of the specified runtime $option . The following options exist:
|
option
|
The specified option is unknown. |
Examples |
|
Helper Functions
prof:void
Signature | prof:void( $value as item()* ) as empty-sequence() |
Summary | Swallows all items of the specified $value and returns an empty sequence. This function is helpful if some code needs to be evaluated and if the resulting value is irrelevant.
|
Properties | The function is non-deterministic: evaluation order will be preserved by the compiler. |
Examples |
|
prof:sleep
Signature | prof:sleep( $ms as xs:integer ) as empty-sequence() |
Summary | Sleeps for the specified number of milliseconds. |
Properties | The function is non-deterministic: evaluation order will be preserved by the compiler. |
prof:human
Signature | prof:human( $number as xs:integer ) as xs:string |
Summary | Returns a human-readable representation of the specified $number .
|
Example |
|
Errors
Code | Description |
---|---|
option
|
The specified option is unknown. |
Changelog
- Version 9.2
- Added:
prof:gc
,prof:runtime
- Updated:
prof:track
: decimal timing results; by default no memory profiling
- Version 9.0
- Added:
prof:track
- Updated: renamed prof:mem to
prof:memory
,prof:time
:$cache
argument removed
- Version 8.5
- Added:
prof:type
(moved from XQuery Module)
- Version 8.1
- Added:
prof:variables
- Version 7.7
- Added:
prof:void
- Version 7.6
- Added:
prof:human
- Version 7.5
- Added:
prof:dump
,prof:current-ms
,prof:current-ns
This module was introduced with Version 7.3.