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.

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

Errors The function is nondeterministic: evaluation order will be preserved by the compiler.

Summary

Measures the execution time and memory consumption required for evaluating the specified $input and returns a map with the results. The following $options are available:

option	default	description
`time`	`true()`	Include execution time in result as `xs:decimal` (unit: milliseconds)
`memory`	`false()`	Include memory consumption in result as `xs:integer` (unit: bytes).
`value`	`true()`	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. It is important to know that this slows down the evaluation time of the query.

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`

Updated: Aggregate parameter added

Signature	prof:time( $input as item(), $label as xs:string? := (), $aggregate as xs:boolean? := false() ) as item()*
Errors	The function is nondeterministic: evaluation order will be preserved by the compiler.
Summary	Measures the time needed to evaluate `$input` and outputs a string to standard error, to the Info View of the GUI, or to the database logs. An optional `$label` may be specified to tag the profiling result. If `$aggregate` is enabled, the measurements will be collected and the total, average, minimum and maximum time and the number of runs will be presented after the query is executed. See `prof:track` for further notes on performance measurements.
Examples	`prof:time(prof:sleep(1000))` Outputs something similar to `1000.99 ms`.

`prof:memory`

Updated: Aggregate parameter added

Signature	prof:memory( $input as item(), $label as xs:string? := (), $aggregate as xs:boolean? := false() ) as item()*
Errors	The function is nondeterministic: evaluation order will be preserved by the compiler.
Summary	Measures the memory allocated by evaluating `$input` and outputs a string to standard error, to the Info View of the GUI, or to the database logs. An optional `$label` may be specified to tag the profiling result. If `$aggregate` is enabled, the measurements will be collected and the average memory consumption and the number of runs will be presented after the query is executed. See `prof:track` for further notes on performance measurements.
Examples	`prof:memory((1 to 100000) ! <a/>)` Output something similar to `5620 kB`.

`prof:current-ms`

Signature	prof:current-ms() as xs:integer
Errors	In 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.
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.
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
Errors	In 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.
Summary	Returns 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`

Updated: Result contains all currently declared variables.

Signature	prof:variables() as empty-sequence()
Errors	The function is nondeterministic: evaluation order will be preserved by the compiler.
Summary	Prints a list of all currently declared variable to standard error, to the Info View of the GUI, or to the database logs.
Examples	`for $x in 1 to 2 return ($x, prof:variables())` Dump the values of `$x` to standard error.

`prof:type`

Updated: String output revised, label parameter added.

Signature	prof:type( $expr as item(), $label as xs:string? := () ) as item()
Summary	Outputs type information for the specified expression and the resulting value. See `fn:trace` for more information on trace output.

`prof:gc`

Signature	prof:gc( $count as xs:integer := () ) as empty-sequence()
Summary	Enforces 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`

Updated: Argument has become optional.

Signature

prof:runtime(
  $option  as enum('used', 'total', 'max', 'processors')?  := ()
) as xs:integer

Summary

Returns a map with JVM runtime values or, if specified, the value of the specified $option. The following options are available:

used: Currently used memory (varies over time, will shrink after garbage collection).
total: Total memory in the Java virtual machine (varies over time).
max: Maximum memory that the Java virtual machine will attempt to use.
processors: number of processors available to the Java virtual machine.

Errors

option The 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()
Errors	The function is nondeterministic: evaluation order will be preserved by the compiler.
Summary	Sleeps for the specified number of milliseconds.

`prof:human`

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