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%'|- valign="top"| width='120' | '''Signature'''|<pre>prof:track( $input as item()*, $options as map(*)? := map { }) as item()*</pre>|- valign="top"| '''Summary'''|Measures the execution time and memory consumption required for evaluating the specified {{Code|$input}} and returns a map with the results. The following {{Code|$options}} are available:* {{Code|time}}: 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.* Profilingmight 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.|- valign="top"| '''Properties'''|The function is ''nondeterministic'': evaluation order will be preserved by the compiler.|- valign="top"| '''Examples'''|* Return a human-readable representation of the memory consumption caused by fetching an XML document. {{Function||fetch:doc}} is used, as <code>fn:doc</code> may already be evaluated at compilation time:<pre lang='xquery'>prof:track(fetch:doc('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 lang='xquery'>map { "memory": 21548400, "value": (2, 4, 6, 8, 10, ...)}</pre>|}

In {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>prof:time( $input as item(), $label as xs:string? := ()) as item()*</pre>|- valign="top"| '''Summary'''|Measures the time needed to evaluate {{VersionCode|7.2$input}}and outputs a string to standard error or, if the GUI is used, to the Info View. An optional {{Code|$label}} argument was added may be specified to tag the functionprofiling result. See {{Function||prof:track}} for further notes.{|- valign="top"|-'''Properties'''| width=The function is ''nondeterministic'90' : evaluation order will be preserved by the compiler.|- valign="top"| '''SignaturesExamples'''|* {{FuncCode|prof:time|$expr as item(prof:sleep(1000)|item()*}}<br />outputs something similar to {{FuncCode|1000.99 ms}}.|} ==prof:timememory== {| width='100%'|- valign="top"| width='120' |$expr as item(), $cache as xs:boolean'''Signature'''|item()*}}<br /pre>{{Func|prof:time|memory( $expr input as item(), $cache as xs:boolean, $label as xs:string|? := ()) as item()*}}</pre>|-valign="top"

|Measures the time needed to evaluate memory allocated by evaluating {{Code|$exprinput}} 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||$labelprof:track}} may for further notes.|- valign="top"| '''Properties'''|The function is ''nondeterministic'': evaluation order will be specified to tag preserved by the profiling resultcompiler.|-valign="top"

* {{Code|prof:timememory(("1 to 100000") ! <a/>)}} may will output something similar to {{Code|255620 kB}}.69 |} ==prof:current-ms== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>prof:current-ms() as xs:integer</pre>|- valign="top"| '''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.|- valign="top"| '''Properties'''|In contrast to {{Code|fn:current-time()}}, the function is ''nondeterministic'' and returns different values every time it is called. Its evaluation order will be preserved by the compiler.|- valign="top"| '''Examples'''|* {{Code|convert:integer-to-dateTime(prof:current-ms())}} returns the current miliseconds in the {{Code|xs:dateTime}} format.|} ==prof:current-ns== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>prof:current-ns() as xs:integer</pre>|- valign="top"| '''Summary'''|Returns the current value of the most precise available system timer in nanoseconds.|- valign="top"| '''Properties'''|In contrast to {{Code|fn:current-time()}}, the function is ''nondeterministic'' and returns different values every time it is called. Its evaluation order will be preserved by the compiler.|- valign="top"| '''Examples'''| Measures the time of an expression:<pre lang='xquery'>let $ns1 := prof:current-ns()return ( (: process to measure :) (1 to 1000001000000)[. = 0], let $ns2 := prof:current-ns() let $ms := ((($ns2 - $ns1) idiv 10000) div 100) return $ms || ' ms')</pre>|} =Debugging Functions= ==prof:dump== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>prof:dump( $input as item()*, true $label as xs:string? := ())as empty-sequence()</pre>|- valign="top"| '''Summary'''|Dumps a serialized representation of {{Code|$input}} may output to {{Code|STDERR}}, optionally prefixed with {{Code|208$label}}, and returns an empty sequence.12 msIf the GUI is used, the dumped result is shown in the [[Graphical User Interface#Visualizations|Info View]].|- valign="top"| '''Properties'''|In contrast to {{Code|fn:trace()}}, the consumed expression will not be passed on.

==prof:memvariables==

In {{Version|7.2}}, the {{Code|$label}} argument was added to the function:{|width='100%'|-valign="top"| width='90120' | '''SignaturesSignature'''|{{Func|prof:mem|$expr as item()|item()*}}<br /pre>{{Func|prof:mem|$expr as itemvariables(), $cache as xs:boolean|itemempty-sequence()*}}<br /pre>{{Func|prof:mem|$expr as item(), $cache as xs:boolean, $label as xs:string|item()*}}|-valign="top"

|Measures the memory allocated by evaluating {{Code|$expr}} Prints a list of all current local and sends it global variable assignments to standard error or, if the GUI is used, to the Info View.<br />If {{Code|$cache}} As every query is set to {{Code|true()}}optimized before being evaluated, not all of the result will original variables may be temporarily cachedvisible in the output. This wayMoreover, a potential iterative execution many variables of the expression (which often yields different memory usage) is blockedfunction calls will disappear because functions are inlined.<br/>A third, optional argument Function inlining can be turned off by setting {{CodeOption|$labelINLINELIMIT}} may to <code>0</code>.|- valign="top"| '''Properties'''|The function is ''nondeterministic'': evaluation order will be specified to tag preserved by the profiling resultcompiler.|-valign="top"

* {{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%'|- valign="top"| width='120' | '''Signature'''|<pre>prof:mbtype( $expr as item()*) as item()*</pre>|- valign="1 top"| '''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:gc== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>prof:gc( $count as xs:integer := ()) as empty-sequence()</pre>|- valign="top"| '''Summary'''|Enforces Java garbage collection. If no {{Code|$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 100000trust the garbage collecting strategies of Java.|} ==prof:runtime== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>prof:runtime( $option as xs:string)as xs:integer</pre>|- valign="top"| '''Summary'''|Returns the value of the specified runtime {{Code|$option}}. The following options are available:* {{Code|max}}: Maximum memory that the Java virtual machine will attempt to use.* {{Code|total}} may output : Total memory in the Java virtual machine (varies over time).* {{Code|0 Bytesused}}: Currently used memory (varies over time, will shrink after garbage collection).* {{Code|processors}}: number of processors available to the Java virtual machine.|- valign="top"|{{Code|option}}|The specified option is unknown.|- valign="top"| '''Examples'''|* <code>prof:mbgc(3), prof:human(prof:runtime('used'))</code> performs some garbage collection and returns the currently used amount of memory in a user-friendly format.|} =Helper Functions= ==prof:void== {| width='100%'|- valign="1 to 100000top", true| width='120' | '''Signature'''|<pre>prof:void( $input as item()*)as empty-sequence()</pre>|- valign="top"| '''Summary'''|Absorbs the specified {{Code|$input}} may output and returns an empty sequence. This function is helpful if some (often nondeterministic or side-effecting) code needs to be evaluated and if the resulting value is not required.|- valign="top"| '''Properties'''|The function is ''nondeterministic'': evaluation order will be preserved by the compiler.|- valign="top"| '''Examples'''|* {{Code|26prof:void(fetch:binary('http://my.rest.678 mbservice'))}}performs an HTTP request and ignores the result.

{|width='100%'|-valign="top"| width='90120' | '''SignaturesSignature'''|{{Func|<pre>prof:sleep|( $ms as xs:integer|) as empty-sequence()*}}<br /pre>|-valign="top"