Changes

=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.* 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.|- 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>|}

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|prof:time|$expr as item()|item()*}}<br /pre>{{Func|prof:time|( $expr input as item(), $cache label as xs:boolean|itemstring? := ()*}}<br />{{Func|prof:time|$expr as item(), $cache as xs:boolean, $label as xs:string|item()*}}</pre>|-valign="top"

|Measures the time needed to evaluate {{Code|$exprinput}} 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||prof:track}} for further notes.|-valign="top"

|The function is ''non-deterministicnondeterministic'': evaluation order will be preserved by the compiler.|-valign="top"

* {{Code|prof:time("1 to 100000")}} may output {{Code|25.69 ms}}.* {{Code|prof:time("1 to 100000", truesleep(1000))}} may output outputs something similar to {{Code|2081000.12 99 ms}}.

==prof:memmemory==

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|prof:mem|$expr as item()|item()*}}<br /pre>{{Func|prof:mem|memory( $expr input as item(), $cache label as xs:boolean|itemstring? := ()*}}<br />{{Func|prof:mem|$expr as item(), $cache as xs:boolean, $label as xs:string|item()*}}</pre>|-valign="top"

|Measures the 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 {{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||prof:track}} for further notes.|-valign="top"

|The function is ''non-deterministicnondeterministic'': evaluation order will be preserved by the compiler.|-valign="top"

* {{Code|prof:memmemory("1 to 100000")}} may output {{Code|0 Bytes}}.* {{Code|prof:mem("1 to 100000", true()! <a/>)}} may will output something similar to {{Code|26.678 mb5620 kB}}.

==prof:sleepcurrent-ms==

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

|Sleeps for Returns the specified 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"

|The In contrast to {{Code|fn:current-time()}}, the function is ''non-deterministicnondeterministic'': 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:humancurrent-ns==

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>prof:human|$number current-ns() as xs:integer|xs:string}}</pre>|-valign="top"

|Returns a human-readable representation the current value of the specified most precise available system timer in nanoseconds.|- valign="top"| '''Properties'''|In contrast to {{Code|$numberfn: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"| '''ExampleExamples'''|Measures the time of an expression:<pre lang='xquery'>let $ns1 := prof:current-ns()return ( (: process to measure :) (1 to 1000000)[. = 0],* {{Code| let $ns2 := prof:humancurrent-ns(16384)}} returns {{Code let $ms := ((($ns2 - $ns1) idiv 10000) div 100) return $ms ||16K}}.' ms')</pre>

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|prof:dump|$expr as item()|empty-sequence()}}<br /pre>{{Func|prof:dump|( $expr input as item()*, $label as xs:string|? := ()) as empty-sequence()}}<br /pre>|-valign="top"

|Dumps a serialized representation of {{Code|$exprinput}} 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]].|-valign="top"

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>prof:variables||() as empty-sequence()}}</pre>|-valign="top"

|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 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 [[Options#INLINELIMIT{{Option|INLINELIMIT]] option }} to <code>0</code>.|-valign="top"

|The function is ''non-deterministicnondeterministic'': evaluation order will be preserved by the compiler.|-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:currenttype== {| width='100%'|-msvalign="top"| width='120' | '''Signature'''|<pre>prof:type( $expr as item()*) as item()*</pre>|- valign="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==

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>prof:current-ms||gc( $count as xs:integer}} := ()) as empty-sequence()<br /pre>|-valign="top"

|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 millisecondsEnforces Java garbage collection.|-| '''Properties'''|In contrast to If no {{Code|fn:current-time()$count}}is supplied, the garbage will be collected once. Please note that this function is ''non-deterministic'' and returns different values every time should only be used for debugging purposes; in productive code, it is called. Its evaluation order will be preserved by the compiler.|-| '''Examples'''|* {{Code|convert:integer-best to-dateTime(prof:current-ms())}} returns trust the current miliseconds in the {{Code|xs:dateTime}} formatgarbage collecting strategies of Java.

==prof:current-nsruntime==

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>prof:current-ns||runtime( $option as xs:string) as xs:integer}}<br /pre>|-valign="top"

|Returns the current value of the most precise specified runtime {{Code|$option}}. The following options are available system timer in nanoseconds.:* {{Code|-max}}: Maximum memory that the Java virtual machine will attempt to use.* {{Code| '''Properties'''total}}: Total memory in the Java virtual machine (varies over time).|In contrast to * {{Code|fnused}}:current-Currently used memory (varies over time(, will shrink after garbage collection).* {{Code|processors}}, : number of processors available to the function is ''nonJava virtual machine.|-deterministic'' and returns different values every time it valign="top"|{{Code|option}}|The specified option is called. Its evaluation order will be preserved by the compilerunknown.|-valign="top"

| Measures the time of an expression:* <pre class="brush:xquery"code>let $ns1 := prof:current-nsgc(3)return ( (: process to measure :) (1 to 1000000)[. = 0], let $ns2 := prof:current-nshuman() let $ms prof:= (runtime(($ns2 - $ns1) idiv 10000) div 100) return $ms || ' msused'))</precode>performs some garbage collection and returns the currently used amount of memory in a user-friendly format.

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>prof:void|( $value input as item()*|) as empty-sequence()}}</pre>|-valign="top"

|Swallows all items of Absorbs the specified {{Code|$valueinput}} and returns an empty sequence. This function is helpful if some (often nondeterministic or side-effecting) code needs to be evaluated and if the actual result resulting value is irrelevantnot required.|-valign="top"

|The function is ''non-deterministicnondeterministic'': evaluation order will be preserved by the compiler.|-valign="top"

==prof:typesleep== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>prof:sleep( $ms as xs:integer) as empty-sequence()</pre>|- valign="top"| '''Summary'''|Sleeps for the specified number of milliseconds.|- valign="top"| '''Properties'''|The function is ''nondeterministic'': evaluation order will be preserved by the compiler.|} ==prof:human==

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>prof:type|human( $expr number as item(xs:integer)*|item()*}}as xs:string</pre>|-valign="top"

|Similar to Returns a human-readable representation of the specified {{Code|$number}}.|- valign="top"| '''Example'''|* {{Code|fnprof:tracehuman($expr, $msg16384)}}, but instead of a userreturns {{Code|16K}}.|} =Errors= {| class="wikitable" width="100%"! width="110"|Code|Description|-defined message, it emits the compile-time type and estimated result size of its argumentvalign="top"|{{Code|option}}|The specified option is unknown.

* Added: [[#prof:type{{Function||prof:type]] }} (moved from [[XQuery Module]])

* Added: [[#prof:variables{{Function||prof:variables]]}}

* Added: [[#prof:void{{Function||prof:void]]}}

* Added: [[#prof:human{{Function||prof:human]]}}

* Added: [[#prof:dump{{Function||prof:dump]]}}, [[#prof:current-ms{{Function||prof:current-ms]]}}, [[#prof:current-ns{{Function||prof:current-ns]]}}