3 Profiling Rival

8.17.0.6

3 Profiling Rival🔗ℹ

Rival’s compiler and evaluator expose a variety of interesting profiling data, which can be accessed via the rival-profile function. Note that all of Rival’s profiling information is not guaranteed to be stable, backward-, or forward-compatible between versions. We do not recommend relying on rival-profile in your code without following Rival development closely.

procedure
(rival-profile machine command) → any/c
machine : rival-machine?
command : symbol?

The rival-profile function is called on a rival-machine? with a command symbol that decribes the kind of profiling information to return. Profiling commands may be added or removed freely across versions; do not rely on them.

The currently-supported command symbols and their return values are:

instructions returns the number of register machine instructions in the compiled machine.
iterations returns the number of re-evaluation iterations needed for the most recent call to rival-apply with the compiled machine. This should be a number from 0 to *rival-max-iterations*, inclusive.
bumps returns the number of unexpected non-convergences detected during the most recent call to rival-apply with the compiled machine. These generally represent internal errors in Rival. While Rival will attempt to handle these "bumps" smoothly, they should still be reported to the developers as a bug.
executions returns a list of "execution" structs, one for every register machine instruction executed by Rival. These executions are stored in a fixed-size buffer (see *rival-profile-executions*) which is retained across rival-apply calls and can fill up. The buffer is emptied by calls to (rival-profile machine 'executions), so make sure to call this function regularly. If the list of "execution"s returned by rival-profile is equal in length to *rival-profile-executions*, you likely filled the buffer and are missing some executions.

struct
(struct execution (name number precision time))
  name : symbol?
  number : natural?
  precision : natural?
  time : flonum?

Each execution corresponds to a single Rival interval operator being executed. The name names the operator, except the special symbol 'adjust, in which case it refers to an internal precision-tuning pass. The number gives its position in the compiled instruction sequence; this allows disambiguating if an expression contains, say, multiple addition operations. The precision is the bf-precision that the operator is executed at, and the time is the time, in milliseconds, that that execution took. Note that, because Rival executes the register machine multiple times, the same operator (with the same name and number) can appear multiple times for a single point. On the other hand, in some iterations Rival might skip some operators, if the precision is unchanged from previous iterations, so not every operator may show up in the executions list the same number of times.

parameter
(*rival-profile-executions*) → natural?
(*rival-profile-executions* executions) → void?
executions : natural?
= 1000

The executions are, for maximum performance, written into a single fixed-size vector allocated when rival-compile is called. To change the size of this struct, set the *rival-profile-executions* during compilation. Once the rival-compile returns, the profiling vector’s size cannot be changed.