Event

Struct representing some exceptional floating point event.

category options:

• :nan
• :inf

evt_type options:

• :injected
• :gen
• :prop
• :kill

FloatTracker config struct

Logger Config

Injector Config

Session Config

Struct to describe a function location; used by the Injector

The avoid field defaults to false—setting this to true will make it so that if that function will not be considered a candidate for injection.

Struct describing parameters for injecting NaNs

Fields

• active::Boolean inject only if true

• n_inject::Int maximum number of NaNs to inject; gets decremented every time a NaN gets injected

• odds::Int inject a NaN with 1:odds probability—higher value → rarer to inject

• functions::Array{FunctionRef} if given, only inject NaNs when within these functions; default is to not discriminate on functions

• libraries::Array{String} if given, only inject NaNs when within this library.

  NOTE: Libraries MUST NOT have a .jl suffix—we strip out that suffix when looking for the name of a library by default, so don't include it here otherwise it will never match.

• record::String if given, record injection invents in a way that can be replayed later with the replay argument.

• replay::String if given, ignore all previous directives and use this file for injection replay.

functions and libraries work together as a union: i.e. the set of possible NaN injection points is a union of the places matched by functions and libraries.

Struct containing all configuration for the logger.

Fields

• filename::String Basename of the file to write logs to.

  Constructors automatically prefix the timestamp to the beginning of this basename so the logs are grouped together chronologically.

• buffersize::Int Number of logs to buffer in memory before writing to file.

  Defaults to 1000. Decrease if you are crashing without getting the logs that you need.

• printToStdOut::Bool Whether or not to write logs to STDOUT; defaults to false.

• allErrors::Bool Record all errors in the *_error_log.txt file.

• cstg::Bool Write logs in CSTG format.

• cstgLineNum::Bool Include the line number in CSTG output.

• cstgArgs::Bool Include arguments to functions in CSTG output.

• maxLogs::Union{Int,Unbounded} Maximum number of events to log; defaults to Unbounded.

• maxFrames::Union{Int,Unbounded} Maximum number of stack frames to print in logging; defaults to Unbounded.

• exclusions::Array{Symbol} Events to not log; defaults to [:prop].

ReplayPoint(counter, check, module_list)

Represents a point where a NaN was injected during program execution.

config_injector(log::InjectorConfig)
config_injector(; args...)

Set the injector for the global FloatTracker configuration instance.

Takes either a InjectorConfig struct, or the same keyword arguments as the InjectorConfig constructor.

Passing a partial list of keyword arguments has the same behavior as it does with config_logger.

config_logger(log::LoggerConfig)
config_logger(; args...)

Set the logger for the global FloatTracker configuration instance.

Takes either a LoggerConfig struct, or the same keyword arguments as the LoggerConfig constructor.

In the case where only a few arguments are specified, it will override only those fields, i.e. the entire LoggerConfig won't be replaced. This is useful, for example, if you need to adjust a field in the middle of a test.

config_session(log::SessionConfig)
config_session(; args...)

Set the session for the global FloatTracker configuration instance.

Takes either a SessionConfig struct, or the same keyword arguments as the SessionConfig constructor.

Passing a partial list of keyword arguments has the same behavior as it does with config_logger.

disable_nan_injection()

Turn off NaN injection.

If you want to re-enable NaN injection after calling disable_nan_injection, consider using the one-argument form of enable_nan_injection(n_inject::Int).

enable_nan_injection(n_inject::Int)

Turn on NaN injection and injection n_inject NaNs. Does not modify odds, function and library lists, or recording/replay state.

enable_nan_injection(; odds::Int = 10, n_inject::Int = 1, functions::Array{FunctionRef} = [], libraries::Array{String} = [])

Turn on NaN injection. Optionally configure the odds for injection, as well as the number of NaNs to inject, and the functions/libraries in which to inject NaNs. Overrides unspecified arguments to their defaults.

event(op, args, result, is_injected = false)

Constructs one or more Event structs based off of the operation.

Uses the argument values and the return result to determine what kind of an event we're looking at here. Types:

• :injected –- injections
• :gen –- generating operations
• :prop –- NaN propagation
• :kill –- killing operations

Returns one or more events in a list

exclude_stacktrace(exclusions = [:prop])

Globally set the types of stack traces to not collect.

See documentation for the event() function for details on the types of events that can be put into this list.

Convenience function; You can also set the stack trace exclusions with a keyword argument to config_logger.

frame_library(frame::StackTraces.StackFrame)::Symbol

Return the name of the library that the current stack frame references.

Returns nothing if unable to find library.

ft_init()

Initialize the global FloatTracker configuration. (Automatically called when using function by __init__)

We need to make this a function, otherwise it can cache the value of the timestamp used for writing unique log files.

injectable_region(i::InjectorConfig, frames::StackTrace)::Bool

Returns whether or not the current point in the code (indicated by the StackTrace) is a valid point to inject a NaN.

record_injection(recording_file::String="ft_recording")

Turn on recording.

replay_injection(replay_file::String)

Sets the injector to read from a replay file.

Note that this overwrites all previous configuration to the injector file, as once you are replaying an injection recording, all other configuration ceases to matter.

should_inject(i::InjectorConfig)

Return whether or not we should inject a NaN.

Decision process:

• Checks whether or not the given injector is active.

• Checks that there are some NaNs remaining to inject.

• Rolls an InjectorConfig.odds-sided die; if 1, proceed, otherwise, don't do anything.

• Checks that we're inside the scope of a function in InjectorConfig.functions OR that we're in a library that we're interested in. If yes, inject.

• Defaults to not injecting.