Difference between revisions of "Profiling Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 1: Line 1:
−
This [[Module Library|XQuery Module]] contains functions for XQuery code.
+
This [[Module Library|XQuery Module]] contains various testing, profiling and helper functions.
  
 
=Conventions=
 
=Conventions=
Line 17: Line 17:
 
| '''Summary'''
 
| '''Summary'''
 
|Measures the time needed to evaluate {{Code|$expr}} and sends it 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, optional argument {{Code|$label}} may be specified to tag the profiling result.
 
|Measures the time needed to evaluate {{Code|$expr}} and sends it 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, optional argument {{Code|$label}} may be specified to tag the profiling result.
 +
|-
 +
| '''Properties'''
 +
|The function is ''non-deterministic'': evaluation order will be preserved by the compiler.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 22: Line 25:
 
* {{Code|prof:time("1 to 100000")}} may output {{Code|25.69 ms}}.
 
* {{Code|prof:time("1 to 100000")}} may output {{Code|25.69 ms}}.
 
* {{Code|prof:time("1 to 100000", true())}} may output {{Code|208.12 ms}}.
 
* {{Code|prof:time("1 to 100000", true())}} may output {{Code|208.12 ms}}.
−
|-
 
−
| '''Properties'''
 
−
|The function is ''non-deterministic'': evaluation order will be preserved by the compiler.
 
 
|}
 
|}
  
Line 36: Line 36:
 
| '''Summary'''
 
| '''Summary'''
 
|Measures the memory allocated by evaluating {{Code|$expr}} and sends it 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, optional argument {{Code|$label}} may be specified to tag the profiling result.
 
|Measures the memory allocated by evaluating {{Code|$expr}} and sends it 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, optional argument {{Code|$label}} may be specified to tag the profiling result.
 +
|-
 +
| '''Properties'''
 +
|The function is ''non-deterministic'': evaluation order will be preserved by the compiler.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 41: Line 44:
 
* {{Code|prof:mb("1 to 100000")}} may output {{Code|0 Bytes}}.
 
* {{Code|prof:mb("1 to 100000")}} may output {{Code|0 Bytes}}.
 
* {{Code|prof:mb("1 to 100000", true())}} may output {{Code|26.678 mb}}.
 
* {{Code|prof:mb("1 to 100000", true())}} may output {{Code|26.678 mb}}.
−
|-
 
−
| '''Properties'''
 
−
|The function is ''non-deterministic'': evaluation order will be preserved by the compiler.
 
 
|}
 
|}
  
Line 117: Line 117:
 
| '''Properties'''
 
| '''Properties'''
 
|In contrast to {{Code|fn:current-time()}}, the function is ''non-deterministic'', as it returns different values every time it is called. Its evaluation order will be preserved by the compiler.
 
|In contrast to {{Code|fn:current-time()}}, the function is ''non-deterministic'', as it returns different values every time it is called. Its evaluation order will be preserved by the compiler.
 +
|}
 +
 +
==prof:swallow==
 +
 +
{{Mark|Introduced with Version 7.6.1:}}
 +
 +
{| width='100%'
 +
|-
 +
| width='90' | '''Signatures'''
 +
|{{Func|prof:swallow|$value as item()*|empty-sequence()}}
 +
|-
 +
| '''Summary'''
 +
|Swallows all items of 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 irrelevant.
 +
|-
 +
| '''Properties'''
 +
|The function is ''non-deterministic'': evaluation order will be preserved by the compiler.
 +
|-
 +
| '''Examples'''
 +
|
 +
* {{Code|prof:swallow(fetch:binary('http://my.rest.service'))}} performs an HTTP request and ignores the result.
 
|}
 
|}
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 7.6.1
 +
 +
* Added: <code>[[#prof:swallow|prof:swallow]]</code>
  
 
;Version 7.6
 
;Version 7.6

Revision as of 14:06, 21 February 2013

This XQuery Module contains various testing, profiling and helper functions.

Conventions

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

Functions

prof:time

Signatures prof:time($expr as item()) as item()*
prof:time($expr as item(), $cache as xs:boolean) as item()*
prof:time($expr as item(), $cache as xs:boolean, $label as xs:string) as item()*
Summary Measures the time needed to evaluate $expr and sends it to standard error or, if the GUI is used, to the Info View.
If $cache is set to true(), the result will be temporarily cached. This way, a potential iterative execution of the expression (which often yields different memory usage) is blocked.
A third, optional argument $label may be specified to tag the profiling result.
Properties The function is non-deterministic: evaluation order will be preserved by the compiler.
Examples
  • prof:time("1 to 100000") may output 25.69 ms.
  • prof:time("1 to 100000", true()) may output 208.12 ms.

prof:mem

Signatures prof:mem($expr as item()) as item()*
prof:mem($expr as item(), $cache as xs:boolean) as item()*
prof:mem($expr as item(), $cache as xs:boolean, $label as xs:string) as item()*
Summary Measures the memory allocated by evaluating $expr and sends it to standard error or, if the GUI is used, to the Info View.
If $cache is set to true(), the result will be temporarily cached. This way, a potential iterative execution of the expression (which often yields different memory usage) is blocked.
A third, optional argument $label may be specified to tag the profiling result.
Properties The function is non-deterministic: evaluation order will be preserved by the compiler.
Examples
  • prof:mb("1 to 100000") may output 0 Bytes.
  • prof:mb("1 to 100000", true()) may output 26.678 mb.

prof:sleep

Signatures prof:sleep($ms as xs:integer) as empty-sequence()
Summary Sleeps for the specified number of milliseconds.
Properties The function is non-deterministic: evaluation order will be preserved by the compiler.

prof:human

Template:Mark

Signatures prof:human($number as xs:integer) as xs:string
Summary Returns a human-readable representation of the specified $number.
Example
  • prof:human(16384) returns 16K.

prof:dump

Signatures prof:dump($expr as item()) as empty-sequence()
prof:dump($expr as item(), $label as xs:string) as empty-sequence()
Summary Dumps a serialized representation of $expr to STDERR, optionally prefixed with $label, and returns an empty sequence. If the GUI is used, the dumped result is shown in the Info View.
Properties In contrast to fn:trace(), the consumed expression will not be passed on.

prof:current-ms

Signatures prof:current-ms() as xs:integer
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.
Properties In contrast to fn:current-time(), the function is non-deterministic, as it returns different values every time it is called. Its evaluation order will be preserved by the compiler.

prof:current-ns

Signatures prof:current-ns() as xs:integer
Summary Returns the current value of the most precise available system timer in nanoseconds.
Properties In contrast to fn:current-time(), the function is non-deterministic, as it returns different values every time it is called. Its evaluation order will be preserved by the compiler.

prof:swallow

Template:Mark

Signatures prof:swallow($value as item()*) as empty-sequence()
Summary Swallows all items of the specified $value and returns an empty sequence. This function is helpful if some code needs to be evaluated and if the actual result is irrelevant.
Properties The function is non-deterministic: evaluation order will be preserved by the compiler.
Examples

Changelog

Version 7.6.1
Version 7.6
Version 7.5

This module was introduced with Version 7.3.

Retrieved from "http://docs.basex.org/index.php?title=Profiling_Module&oldid=9019"