Changes

This [[Module Library|XQuery Module]] contains various testingfunctions to test and profile code, profiling and helper functionsto dump information to standard output.

All functions and errors in this module are assigned to the <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><nowiki>http://basex.org/errors</nowiki></code> namespace, which is statically bound to the {{Code|bxerr}} prefix.

=Performance Functions=

==prof:timetrack==

|{{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()*}}

|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}} is set to 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 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 quality of the profiling resultmeasurement.

* {{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==

|{{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()*}}

|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.

* {{Code|prof:memtime("1 to 100000")}} may output {{Code|0 Bytes}}.* {{Code|prof:mem("1 to 100000", truesleep(1000))}} may output outputs something similar to {{Code|261000.678 mb99 ms}}.

==prof:sleepmemory==

|{{Func|prof:sleepmemory|$ms expr as xs:integeritem()|empty-sequenceitem()*}}<br />{{Func|prof:memory|$expr as item(), $label as xs:string|item()*}}

|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.

==prof:humancurrent-ms==

|{{Func|prof:humancurrent-ms||$number as xs:integer|xs:string}}<br />

|Returns a human-readable representation the number of milliseconds passed since 1970/01/01 UTC. The granularity of the specified 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|$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'''

* {{Code|convert:integer-to-dateTime(prof:humancurrent-ms(16384))}} returns the current miliseconds in the {{Code|xs:dateTime}} format.|} ==prof:current-ns== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|prof:current-ns||xs:integer}}<br />|-| '''Summary'''|Returns the current value of the most precise available system timer in nanoseconds.|-| '''Properties'''|In contrast to {{Code|16Kfn: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>

==prof:current-mstype==

|{{Func|prof:current-mstype|$expr as item()*|xs:integeritem()*}}<br />

|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 Similar to {{Code|fn:current-timetrace($expr, $msg)}}, the function is ''nonbut instead of a user-deterministic''defined message, as it returns different values every emits the compile-time it is called. Its evaluation order will be preserved by the compilertype and estimated result size of its argument.

=Helper Functions= ==prof:current-nsvoid==

|{{Func|prof:current-nsvoid|$value as item()*|xs:integerempty-sequence()}}<br />

|Returns Swallows all items of the current specified {{Code|$value of }} and returns an empty sequence. This function is helpful if some code needs to be evaluated and if the most precise available system timer in nanosecondsactual result is irrelevant.

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

==prof:voidsleep==

|{{Func|prof:voidsleep|$value ms as item()*xs:integer|empty-sequence()}}<br />

|Swallows all items of Sleeps for the specified {{Code|$value}} and returns an empty sequence. This function is helpful if some code needs to be evaluated and if the actual result is irrelevantnumber of milliseconds.

| '''ExamplesSummary'''|Returns a human-readable representation of the specified {{Code|$number}}.|-| '''Example'''

* {{Code|prof:voidhuman(fetch:binary('http://my.rest.service')16384)}} performs an HTTP request and ignores the resultreturns {{Code|16K}}.

* Added: <code>[[#prof:variables|prof:variables]]</code>

* Added: <code>[[#prof:void|prof:void]]</code>

* Added: <code>[[#prof:human|prof:human]]</code>

* Added: <code>[[#prof:dump|prof:dump]]</code>, <code>[[#prof:current-ms|prof:current-ms]]</code>, <code>[[#prof:current-ns|prof:current-ns]]</code>