Difference between revisions of "Profiling Module"
Jump to navigation
Jump to search
(11 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | This [[Module Library|XQuery Module]] contains various functions to test and profile | + | This [[Module Library|XQuery Module]] contains various functions to test and profile code, and to dump information to standard output. |
=Conventions= | =Conventions= | ||
Line 8: | Line 8: | ||
==prof:track== | ==prof:track== | ||
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|prof:track|$ | + | |{{Func|prof:track|$expression as item()|item()*}}<br/>{{Func|prof:track|$expression as item(), $options as map(*)?|item()*}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
|Measures the execution time and memory consumption required for evaluating the specified {{Code|$expression}} and returns a map with the results. The following {{Code|$options}} are available: | |Measures the execution time and memory consumption required for evaluating the specified {{Code|$expression}} and returns a map with the results. The following {{Code|$options}} are available: | ||
− | * {{Code|memory}}: | + | * {{Code|memory}}: Include memory consumption in result (unit: bytes; default: true). |
− | * {{Code|time}}: | + | * {{Code|time}}: Include execution time in result (unit: milliseconds; default: true). |
− | * {{Code|value}}: | + | * {{Code|value}}: Include value in result (default: true). |
Helpful notes: | Helpful notes: | ||
− | * Profiling might change the behavior of your code: An expression that might be executed iteratively will be cached by the profiling function. | + | * If you are not interested in some of the returned results, you should disable them to save time and memory. |
+ | * Profiling might change the execution behavior of your code: An expression that might be executed iteratively will be cached by the profiling function. | ||
* If a value has a compact internal representation, memory consumption will be very low, even if the serialized result may consume much more memory. | * If a value has a compact internal representation, memory consumption will be very low, even if the serialized result may consume much more memory. | ||
− | * | + | * Please note that memory profiling is only approximative, so it can be quite misleading. If the memory option is enabled, main-memory will be garbage-collected before and after evaluation to improve the quality of the measurement. |
|- | |- | ||
| '''Properties''' | | '''Properties''' | ||
Line 30: | Line 29: | ||
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
− | |The function call <code>prof:track((1 to 1000000)[. mod 2 = 0])</code> will return something similar to: | + | | |
+ | * Return a human-readable representation of the memory consumption caused by fetching an XML document (<code>fetch:xml</code> is used, as <code>fn:doc</code> may already be evaluated at compilation time): | ||
+ | <pre class="brush:xquery"> | ||
+ | prof:track(fetch:xml('factbook.xml'))?memory | ||
+ | => prof:human() | ||
+ | </pre> | ||
+ | * The function call <code>prof:track((1 to 1000000)[. mod 2 = 0], map { 'time': false() })</code> will return something similar to: | ||
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
map { | map { | ||
− | "memory": | + | "memory": 21548400, |
− | |||
"value": (2, 4, 6, 8, 10, ...) | "value": (2, 4, 6, 8, 10, ...) | ||
} | } | ||
Line 41: | Line 45: | ||
==prof:time== | ==prof:time== | ||
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
Line 50: | Line 52: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Measures the time needed to evaluate {{Code|$expr}} and outputs a string to standard error or, if the GUI is used, to the Info View. | + | |Measures the time needed to evaluate {{Code|$expr}} and outputs a string to standard error or, if the GUI is used, to the Info View. An optional {{Code|$label}} may be specified to tag the profiling result. See {{Function|Profiling|prof:track}} for further notes. |
− | |||
− | |||
|- | |- | ||
| '''Properties''' | | '''Properties''' | ||
Line 63: | Line 63: | ||
==prof:memory== | ==prof:memory== | ||
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
Line 72: | Line 70: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Measures the memory allocated by evaluating {{Code|$expr}} and outputs a string to standard error or, if the GUI is used, to the Info View. An optional {{Code|$label}} may be specified to tag the profiling result. | + | |Measures the memory allocated by evaluating {{Code|$expr}} and outputs a string to standard error or, if the GUI is used, to the Info View. An optional {{Code|$label}} may be specified to tag the profiling result. See {{Function|Profiling|prof:track}} for further notes. |
− | |||
− | |||
− | |||
|- | |- | ||
| '''Properties''' | | '''Properties''' |
Revision as of 13:23, 24 May 2018
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
Signatures | prof:track($expression as item()) as item()* 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 |
prof:track(fetch:xml('factbook.xml'))?memory => prof:human()
map { "memory": 21548400, "value": (2, 4, 6, 8, 10, ...) } |
prof:time
Signatures | prof:time($expr as item()) as item()* 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
Signatures | prof:memory($expr as item()) as item()* 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
Signatures | 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
Signatures | 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:
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' ) |
Debugging Functions
prof:dump
Signatures | prof:dump($expr as item()) as empty-sequence() 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
Signatures | 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 the INLINELIMIT option to 0 .
|
Properties | The function is non-deterministic: evaluation order will be preserved by the compiler. |
Examples |
|
prof:type
Signatures | 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.
|
Helper Functions
prof:void
Signatures | 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 actual result is irrelevant.
|
Properties | The function is non-deterministic: evaluation order will be preserved by the compiler. |
Examples |
|
prof:sleep
Signatures | 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
Signatures | prof:human($number as xs:integer) as xs:string
|
Summary | Returns a human-readable representation of the specified $number .
|
Example |
|
Changelog
- Version 9.0
- Added: prof:track
- Updated: renamed prof:mem to prof:memory
- 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.