Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
{{Mark|Introduced with Version 7.6==prof:}}current-ns==
{{Mark|Introduced with Version 7.6.1:}}
[[Category:XQuery]]
→prof:dump
This [[Module Library|XQuery Module]] contains various testingfunctions to test and profile code, profiling and helper functionsto dump information to standard output.
=Conventions=
All functions and errors in this module are assigned to the {{Code|<code><nowiki>http://basex.org/modules/prof}} </nowiki></code> namespace, which is statically bound to the {{Code|prof}} prefix.<br/>All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
=Performance Functions=
==prof:timetrack== {{Mark|Updated with Version 9.2:}} Decimal timing results; by default no memory profiling.
{| width='100%'
|-
| width='90120' | '''Signatures'''|{{Func|prof:timetrack|$expr expression as item()|item()*}}<br />{{Func|prof:timetrack|$expr expression as item(), $cache options as xs:boolean|itemmap()*}}<br />{{Func|prof:time|$expr as item(), $cache as xs:boolean, $label as xs:string?|item()*}}
|-
| '''Summary'''
|Measures the execution time needed to evaluate and memory consumption required for evaluating the specified {{Code|$exprexpression}} and sends it to standard error or, if returns a map with the GUI is used, to the Info Viewresults.<br />If The following {{Code|$cacheoptions}} are available:* {{Code|time}} is set to : Include execution time in result as {{Code|xs:decimal}} (unit: milliseconds; default: true).* {{Code|memory}}: Include memory consumption in result as {{Code|xs:integer}} (unit: bytes; default: false).* {{Code|value}}: Include value in result (default: true).Helpful notes:* If you are not interested in some of the returned results, you should disable them to save time and memory.* Profiling might change the result execution behavior of your code: An expression that might be executed iteratively will be temporarily cachedby the profiling function. This way* If a value has a compact internal representation, memory consumption will be very low, a potential iterative execution of even if the expression (which often yields different serialized result may consume much more memory.* Please note that memory usage) profiling is blockedonly approximative, so it can be quite misleading.<br/>A thirdIf the memory option is enabled, optional argument {{Code|$label}} may main-memory will be specified garbage-collected before and after evaluation to tag improve the profiling resultquality of the measurement.
|-
| '''Properties'''
| '''Examples'''
|
* {{Code|profReturn 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="1 to 100000brush:xquery">prof:track(fetch:xml('factbook.xml')}} may output {{Code|25.69 ms}}.)?memory=> prof:human()</pre>* {{Code|The function call <code>prof:timetrack(("1 to 100000"1000000)[. mod 2 = 0], truemap { 'time': false()})}} may output </code> will return something similar to:<pre class="brush:xquery">map {{Code|208 "memory": 21548400, "value": (2, 4, 6, 8, 10, ...12 ms)}}.</pre>
|}
==prof:memtime==
{| width='100%'
|-
| width='90120' | '''Signatures'''|{{Func|prof:memtime|$expr as item()|item()*}}<br />{{Func|prof:memtime|$expr as item(), $cache as xs:boolean|item()*}}<br />{{Func|prof:mem|$expr as item(), $cache as xs:boolean, $label as xs:string|item()*}}
|-
| '''Summary'''
|Measures the memory allocated by evaluating time needed to evaluate {{Code|$expr}} and sends it outputs a string to standard error or, if the GUI is used, to the Info View.<br />If {{Code|$cache}} is set to {{Code|true()}}, the result will be temporarily cached. This way, a potential iterative execution of the expression (which often yields different memory usage) is blocked.<br/>A third, An optional argument {{Code|$label}} may be specified to tag the profiling result. See {{Function|Profiling|prof:track}} for further notes.
|-
| '''Properties'''
| '''Examples'''
|
* {{Code|prof:mbtime("1 to 100000")}} may output {{Code|0 Bytes}}.* {{Code|prof:mb("1 to 100000", truesleep(1000))}} may output outputs something similar to {{Code|261000.678 mb99 ms}}.
|}
==prof:sleepmemory==
{| width='100%'
|-
| width='90120' | '''Signatures'''|{{Func|prof:sleepmemory|$ms expr as xs:integeritem()|empty-sequenceitem()*}}<br />{{Func|prof:memory|$expr as item(), $label as xs:string|item()*}}
|-
| '''Summary'''
|Sleeps for 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 number of millisecondsto tag the profiling result. See {{Function|Profiling|prof:track}} for further notes.
|-
| '''Properties'''
|The function is ''non-deterministic'': evaluation order will be preserved by the compiler.
|-
| '''Examples'''
|
* {{Code|prof:memory((1 to 100000) ! <a/>)}} will output something similar to {{Code|5620 kB}}.
|}
==prof:humancurrent-ms== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|prof:current-ms||xs:integer}}<br />|-| '''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 {{Code|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'''|* {{Code|convert:integer-to-dateTime(prof:current-ms())}} returns the current miliseconds in the {{Code|xs:dateTime}} format.|}
{| width='100%'
|-
| width='90120' | '''Signatures'''|{{Func|prof:humancurrent-ns||$number as xs:integer|xs:string}}<br />
|-
| '''Summary'''
|Returns a human-readable representation the current value of the specified most precise available system timer in nanoseconds.|-| '''Properties'''|In contrast to {{Code|$numberfn: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.
|-
| '''ExampleExamples'''|Measures the time of an expression:<pre class="brush:xquery">let $ns1 := prof:current-ns()return ( (: process to measure :) (1 to 1000000)[. = 0],* {{Code| let $ns2 := prof:humancurrent-ns() let $ms := (16384(($ns2 - $ns1)}} returns {{Codeidiv 10000) div 100) return $ms |16K}}.| ' ms')</pre>
|}
=Debugging Functions=
==prof:dump==
{| width='100%'
|-
| width='90120' | '''Signatures'''|{{Func|prof:dump|$expr as item()*|empty-sequence()}}<br />{{Func|prof:dump|$expr as item()*, $label as xs:string|empty-sequence()}}<br />
|-
| '''Summary'''
|}
==prof:current-msvariables==
{| width='100%'
|-
| width='90120' | '''Signatures'''|{{Func|prof:current-msvariables||xs:integerempty-sequence()}}<br />
|-
| '''Summary'''
|Returns Prints a list of all current local and global variable assignments to standard error or, if the GUI is used, to the number of milliseconds passed since 1970Info View.<br /01/01 UTC. The granularity >As every query is optimized before being evaluated, not all of the value depends on the underlying operating system and original variables may be largervisible in the output. For exampleMoreover, many operating systems measure time in units variables of tens of millisecondsfunction calls will disappear because functions are inlined. Function inlining can be turned off by setting {{Option|INLINELIMIT}} to <code>0</code>.
|-
| '''Properties'''
|In contrast The function is ''non-deterministic'': evaluation order will be preserved by the compiler.|-| '''Examples'''|* {{Code|for $x in 1 to 2 return ($x, prof:variables())}} will dump the values of <code>$x</code> to standard error.|} ==prof:type== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|prof:type|$expr as item()*|item()*}}|-| '''Summary'''|Similar to {{Code|fn:current-timetrace($expr, $msg)}}, but instead of a user-defined message, it emits the function is compile-time type and estimated result size of its argument.|} ==prof:gc== {{Mark|Introduced with Version 9.2.}} {| width='100%'non|-deterministic| width='120' | '''Signatures''', |{{Func|prof:gc||empty-sequence()}}<br/>{{Func|prof:gc|$count as it returns different values every time it xs:integer|empty-sequence()}}|-| '''Summary'''|Enforces Java garbage collection. If no {{Code|$count}} is calledsupplied, garbage will be collected once. Its evaluation order will Please note that this function should only be preserved by used for debugging purposes; in productive code, it is best to trust the compilergarbage collecting strategies of Java.
|}
==prof:current-nsruntime== {{Mark|Introduced with Version 9.2.}}
{| width='100%'
|-
| width='90120' | '''Signatures'''|{{Func|prof:current-nsruntime|$name of xs:string|xs:integer}}<br />
|-
| '''Summary'''
|Returns the current value of the most precise specified runtime {{Code|$option}}. The following options exist:* {{Code|max}}: Maximum memory that the Java virtual machine will attempt to use.* {{Code|total}}: Total memory in the Java virtual machine (varies over time).* {{Code|used}}: Currently used memory (varies over time, will shrink after garbage collection).* {{Code|processors}}: number of processors available system timer in nanosecondsto the Java virtual machine.|-|{{Code|option}}|The specified option is unknown.
|-
| '''PropertiesExamples'''|In contrast to {{Code|fn* <code>prof:current-timegc(3)}}, the function is prof:human(prof:runtime('used'non-deterministic'', as it ))</code> performs some garbage collection and returns different values every time it is called. Its evaluation order will be preserved by the compilercurrently used amount of memory in a user-friendly format.
|}
=Helper Functions=
==prof:void==
{| width='100%'
|-
| width='90120' | '''Signatures'''
|{{Func|prof:void|$value as item()*|empty-sequence()}}
|-
|
* {{Code|prof:void(fetch:binary('http://my.rest.service'))}} performs an HTTP request and ignores the result.
|}
==prof:sleep==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|prof:sleep|$ms as xs:integer|empty-sequence()}}<br />
|-
| '''Summary'''
|Sleeps for the specified number of milliseconds.
|-
| '''Properties'''
|The function is ''non-deterministic'': evaluation order will be preserved by the compiler.
|}
==prof:human==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|prof:human|$number as xs:integer|xs:string}}
|-
| '''Summary'''
|Returns a human-readable representation of the specified {{Code|$number}}.
|-
| '''Example'''
|
* {{Code|prof:human(16384)}} returns {{Code|16K}}.
|}
=Errors=
{| class="wikitable" width="100%"
! width="110"|Code
|Description
|-
|{{Code|option}}
|The specified option is unknown.
|}
=Changelog=
;Version 79.6.12
* Added: [[#prof:gc|prof:gc]], [[#prof:runtime|prof:runtime]]* Updated: [[#prof:track|prof:track]]: decimal timing results; by default no memory profiling ;Version 9.0 * Added: [[#prof:track|prof:track]]* Updated: renamed prof:mem to [[#prof:memory|prof:memory]], [[#prof:time|prof:time]]: <code>$cache</code> argument removed ;Version 8.5 * Added: [[#prof:type|prof:type]] (moved from [[XQuery Module]]) ;Version 8.1 * Added: [[#prof:variables|prof:variables]] ;Version 7.7 * Added: [[#prof:void|prof:void]]</code>
;Version 7.6
* Added: <code>[[#prof:human|prof:human]]</code>
;Version 7.5
* Added: <code>[[#prof:dump|prof:dump]]</code>, <code>[[#prof:current-ms|prof:current-ms]]</code>, <code>[[#prof:current-ns|prof:current-ns]]</code>
This module was introduced with Version 7.3.
