Changes

This [[Module Library|XQuery Module]] contains various functions for XQuery to test and profile code, and to dump information to standard output.

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:track== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|prof:track|$expression as item()|item()*}}<br/>{{Func|prof:track|$expression as item(), $options as map(*)?|item()*}}|-| '''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:* {{Code|memory}}: Include memory consumption in result (unit: bytes; default: true).* {{Code|time}}: Include execution time in result (unit: milliseconds; default: true).* {{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 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.* 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'''|The function is ''non-deterministic'': evaluation order will be preserved by the compiler.|-| '''Examples'''|* 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">map { "memory": 21548400, "value": (2, 4, 6, 8, 10, ...)}</pre>|}

{|width='100%'

| width='90120' | '''Signatures'''|{{Func|prof:time|$expr as item()|item()*}}<br />{{Func|prof:time|$expr as item(), $cache as xs:boolean|item()*}}<br />{{Func|prof:time|$expr as item(), $cache as xs:boolean, $label as xs:string|item()*}}

|Measures the 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 An optional {{Code|$cachelabel}} is set may be specified to {{Code|true()}}, tag the profiling 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, optional argument See {{CodeFunction|Profiling|$labelprof:track}} may for further notes.|-| '''Properties'''|The function is ''non-deterministic'': evaluation order will be specified to tag preserved by the profiling resultcompiler.

* {{Code|prof:time("1 to 100000"prof:sleep(1000))}} may output outputs something similar to {{Code|251000.69 99 ms}}.|} ==prof:memory== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|prof:memory|$expr as item()|item()* }}<br/>{{CodeFunc|prof:timememory|$expr as item("1 to 100000"), true$label as xs:string|item())*}}|-| '''Summary'''|Measures the memory allocated by evaluating {{Code|$expr}} may output and outputs a string to standard error or, if the GUI is used, to the Info View. An optional {{Code|208$label}} may be specified to tag the profiling result.12 msSee {{Function|Profiling|prof:track}}for further notes.

|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:memcurrent-ms==

{|width='100%'

| width='90120' | '''Signatures'''|{{Func|prof:memcurrent-ms|$expr as item()|item()*}}<br />{{Func|prof:mem|$expr as item(), $cache as xs:boolean|item()*integer}}<br />{{Func|prof:mem|$expr as item(), $cache as xs:boolean, $label as xs:string|item()*}}

|Measures Returns the memory allocated by evaluating {{Code|$expr}} number of milliseconds passed since 1970/01/01 UTC. The granularity of the value depends on the underlying operating system and sends it to standard error ormay be larger. For example, if the GUI is used, to the Info Viewmany operating systems measure time in units of tens of milliseconds.<br />If {{Code|-| '''Properties'''|$cache}} is set In contrast to {{Code|truefn:current-time()}}, the result will be temporarily cached. This way, a potential iterative execution of the expression (which often yields function is ''non-deterministic'' and returns different memory usage) values every time it is blockedcalled.<br/>A third, optional argument {{Code|$label}} may Its evaluation order will be specified to tag preserved by the profiling resultcompiler.

* {{Code|convert:integer-to-dateTime(prof:mbcurrent-ms("1 to 100000"))}} may output returns the current miliseconds in the {{Code|0 Bytesxs:dateTime}}format.* |} ==prof:current-ns== {| width='100%'|-| width='120' | '''Signatures'''|{Code{Func|prof:mb("1 to 100000", true())current-ns||xs:integer}} may output {{Code<br />|-| '''Summary'''|26.678 mb}}Returns the current value of the most precise available system timer in nanoseconds.

|The 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'''| Measures the time of an expression:<pre class="brush: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')</pre>

=Debugging Functions= ==prof:dump== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|prof:dump|$expr as item()|empty-sequence()}}<br />{{Func|prof:dump|$expr as item(), $label as xs:string|empty-sequence()}}<br />|-| '''Summary'''|Dumps a serialized representation of {{Code|$expr}} to {{Code|STDERR}}, optionally prefixed with {{Code|$label}}, and returns an empty sequence. If the GUI is used, the dumped result is shown in the [[Graphical User Interface#Visualizations|Info View]].|-| '''Properties'''|In contrast to {{Code|fn:trace()}}, the consumed expression will not be passed on.|} ==prof:sleepvariables==

{|width='100%'

| width='90120' | '''Signatures'''|{{Func|prof:sleepvariables|$ms as xs:integer|empty-sequence()*}}<br />

|Sleeps for Prints a list of all current local and global variable assignments to standard error or, if the GUI is used, to the Info View.<br />As every query is optimized before being evaluated, not all of the specified number original variables may be visible in the output. Moreover, many variables of millisecondsfunction calls will disappear because functions are inlined. Function inlining can be turned off by setting the [[Options#INLINELIMIT|INLINELIMIT]] option to <code>0</code>.

|The function is ''non-deterministic'': evaluation order will be preserved by the compiler.|-| '''Examples'''|* {{Code|for $x in 1 to 2 return 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:trace($expr, $msg)}}, but instead of a user-defined message, it emits the compile-time type and estimated result size of its argument.

==prof:current-ms=Helper Functions=

{{Mark|Introduced with Version 7.4==prof:}}void==

{|width='100%'

| width='90120' | '''Signatures'''|{{Func|prof:current-msvoid|$value as item()*|xs:integerempty-sequence()}}<br />

|Returns the number of milliseconds passed since 1970/01/01 UTC. The granularity Swallows all items of the specified {{Code|$value depends on the underlying operating system }} and may returns an empty sequence. This function is helpful if some code needs to be larger. For example, many operating systems measure time in units of tens of millisecondsevaluated and if the actual result is irrelevant.

|In contrast to The function is ''non-deterministic'': evaluation order will be preserved by the compiler.|-| '''Examples'''|* {{Code|fnprof:current-timevoid(fetch:binary('http://my.rest.service'))}}, performs an HTTP request and ignores the function is ''non-deterministic'', as it returns different values every time it is calledresult.

==prof:currentsleep== {| width='100%'|-ns=| 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.|}

{{Mark|Introduced with Version 7.4==prof:}}human==

{|width='100%'

| width='90120' | '''Signatures'''|{{Func|prof:current-nshuman|$number as xs:integer|xs:integerstring}}<br />

|Returns the current value a human-readable representation of the most precise available system timer in nanosecondsspecified {{Code|$number}}.

| '''PropertiesExample'''|In contrast to * {{Code|fnprof:current-timehuman(16384)}}, the function is ''non-deterministic'', as it returns different values every time it is called{{Code|16K}}.

;Version 79.40 * Added: [[#prof:track|prof:track]]* Updated: renamed prof:mem to [[#prof:memory|prof:memory]] ;Version 8.5 * Added: [[#prof:type|prof:type]] (moved from [[XQuery Module]]) ;Version 8.1

* Added: <code>[[#prof:variables|prof:variables]] ;Version 7.7 * Added: [[#prof:void|prof:void]] ;Version 7.6 * Added: [[#prof:human|prof:human]] ;Version 7.5 * Added: [[#prof:dump|prof:dump]], [[#prof:current-ms|prof:current-ms]]</code>, <code>[[#prof:current-ns|prof:current-ns]]</code>