Main Page » XQuery » Functions » Profiling Functions

Profiling Functions

This module contains various functions to test and profile code, and to send information to standard output.

Removed: The following functions have been removed in favor of new XQuery 4 standard functions:

BaseX 10 XQuery 4
prof:dump fn:message
prof:void fn:void

Conventions

All functions and errors in this module are assigned to the http://basex.org/modules/prof namespace, which is statically bound to the prof prefix.

Performance Functions

prof:track

Signature
prof:track(
  $input    as item()*,
  $options  as map(*)?  := {}
) as item()*
ErrorsThe function is nondeterministic: evaluation order will be preserved by the compiler.
SummaryMeasures the execution time and memory consumption required for evaluating the specified $input and returns a map with the results. The following $options are available:
optiondefaultdescription
timetrue() Include execution time in result as xs:decimal (unit: milliseconds)
memoryfalse() Include memory consumption in result as xs:integer (unit: bytes).
valuetrue() Include value in result.

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.
Examples
prof:track(fetch:doc('factbook.xml'))?memory
=> prof:human()
Return a human-readable representation of the memory consumption caused by fetching an XML document. fetch:doc is used, as fn:doc may already be evaluated at compilation time.
{ "memory": 21548400, "value": (2, 4, 6, 8, 10, ...) }
The function call prof:track((1 to 1000000)[. mod 2 = 0], { 'time': false() }) will return something similar to.

prof:time

Signature
prof:time(
  $input  as item(),
  $label  as xs:string?  := ()
) as item()*
ErrorsThe function is nondeterministic: evaluation order will be preserved by the compiler.
SummaryMeasures the time needed to evaluate $input and outputs a string to standard error or, if the GUI is used, to the Info View. An optional $label may be specified to tag the profiling result. See prof:track for further notes.
Examples
prof:time(prof:sleep(1000))
Outputs something similar to 1000.99 ms.

prof:memory

Signature
prof:memory(
  $input  as item(),
  $label  as xs:string?  := ()
) as item()*
ErrorsThe function is nondeterministic: evaluation order will be preserved by the compiler.
SummaryMeasures the memory allocated by evaluating $input and outputs a string to standard error or, if the GUI is used, to the Info View. An optional $label may be specified to tag the profiling result. See prof:track for further notes.
Examples
prof:memory((1 to 100000) ! <a/>)
Output something similar to 5620 kB.

prof:current-ms

Signature
prof:current-ms() as xs:integer
ErrorsIn contrast to 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.
SummaryReturns 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.
Examples
convert:integer-to-dateTime(prof:current-ms())
Returns the current milliseconds in the xs:dateTime format.

prof:current-ns

Signature
prof:current-ns() as xs:integer
ErrorsIn contrast to 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.
SummaryReturns the current value of the most precise available system timer in nanoseconds.
Examples
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'
)
Measures the time of an expression.

Debugging Functions

prof:variables

Signature
prof:variables() as empty-sequence()
ErrorsThe function is nondeterministic: evaluation order will be preserved by the compiler.
SummaryPrints a list of all current local and global variable assignments to standard error or, if the GUI is used, to the Info View. 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 INLINELIMIT to 0.
Examples
for $x in 1 to 2
return ($x, prof:variables())
Dump the values of $x to standard error.

prof:type

Signature
prof:type(
  $expr  as item()*
) as item()*
SummarySimilar to 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

Signature
prof:gc(
  $count  as xs:integer  := ()
) as empty-sequence()
SummaryEnforces Java garbage collection. If no $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 trust the garbage collecting strategies of Java.

prof:runtime

Signature
prof:runtime(
  $option  as enum('max', 'total', 'used', 'processors')
) as xs:integer
SummaryReturns the JVM values of the specified runtime $option. The following options are available:
  • max: Maximum memory that the Java virtual machine will attempt to use.
  • total: Total memory in the Java virtual machine (varies over time).
  • used: Currently used memory (varies over time, will shrink after garbage collection).
  • processors: number of processors available to the Java virtual machine.
Errors
optionThe specified option is unknown.
Examples
prof:gc(3),
prof:human(prof:runtime('used'))
Performs some garbage collection and returns the currently used amount of memory in a user-friendly format.

Helper Functions

prof:sleep

Signature
prof:sleep(
  $ms  as xs:integer
) as empty-sequence()
ErrorsThe function is nondeterministic: evaluation order will be preserved by the compiler.
SummarySleeps for the specified number of milliseconds.

prof:human

Signature
prof:human(
  $number  as xs:integer
) as xs:string
SummaryReturns a human-readable representation of the specified $number.
Examples
prof:human(16384)
Result: '16 kB'

Errors

CodeDescription
optionThe specified option is unknown.

Changelog

Version 11.0Version 9.2Version 9.0Version 8.5Version 8.1Version 7.7
  • Added: prof:void
Version 7.6Version 7.5Version 7.3
  • Added: New module added.

⚡Generated with XQuery