@eagleoutice/flowr/benchmark/slicer.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

/**
 * Provides a top-level slicer that can be used to slice code *and* retrieve stats.
 * @module
 */
import type { MergeableRecord } from '../util/objects';
import type { DataflowInformation } from '../dataflow/info';
import type { SliceResult } from '../slicing/static/slicer-types';
import type { ReconstructionResult } from '../reconstruct/reconstruct';
import type { PerSliceStats, SlicerStats } from './stats/stats';
import type { NormalizedAst } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
import type { SlicingCriteria } from '../slicing/criterion/parse';
import type { RParseRequestFromFile, RParseRequestFromText } from '../r-bridge/retriever';
import type { SlicingCriteriaFilter } from '../slicing/criterion/collect-all';
import type { AutoSelectPredicate } from '../reconstruct/auto-select/auto-select-defaults';
import type { KnownParserName } from '../r-bridge/parser';
/**
 * The logger to be used for benchmarking as a global object.
 */
export declare const benchmarkLogger: import("tslog").Logger<import("tslog").ILogObj>;
/**
 * Returns the stats but also the result of all setup steps (parsing, normalization, and the dataflow analysis) during the slicing.
 * This is useful for debugging and visualizing the slicing process.
 */
export interface BenchmarkSlicerStats extends MergeableRecord {
    /** the measurements obtained during the benchmark */
    stats: SlicerStats;
    /** the initial and unmodified AST produced by the R side/the 'parse' step */
    parse: string;
    /** the normalized AST produced by the 'normalization' step, including its parent decoration */
    normalize: NormalizedAst;
    /** the dataflow graph produced by the 'dataflow' step */
    dataflow: DataflowInformation;
}
/**
 * Additionally to {@link BenchmarkSlicerStats}, this contains the results of a *single* slice.
 * In other words, it holds the results of the `slice` and `reconstruct` steps.
 */
export interface BenchmarkSingleSliceStats extends MergeableRecord {
    /** the measurements obtained during the single slice */
    stats: PerSliceStats;
    /** the result of the 'slice' step */
    slice: SliceResult;
    /** the final code, as the result of the 'reconstruct' step */
    code: ReconstructionResult;
}
/**
 * The type of sampling strategy to use when slicing all possible variables.
 *
 * - `'random'`: Randomly select the given number of slicing criteria.
 * - `'equidistant'`: Select the given number of slicing criteria in an equidistant manner.
 */
export type SamplingStrategy = 'random' | 'equidistant';
export declare class BenchmarkSlicer {
    /** Measures all data recorded *once* per slicer (complete setup up to the dataflow graph creation) */
    private readonly commonMeasurements;
    private readonly perSliceMeasurements;
    private readonly deltas;
    private readonly parserName;
    private stats;
    private loadedXml;
    private dataflow;
    private normalizedAst;
    private totalStopwatch;
    private finished;
    private executor;
    private parser;
    constructor(parserName: KnownParserName);
    /**
     * Initialize the slicer on the given request.
     * Can only be called once for each instance.
     */
    init(request: RParseRequestFromFile | RParseRequestFromText, autoSelectIf?: AutoSelectPredicate, threshold?: number): Promise<void>;
    private calculateStatsAfterInit;
    /**
     * Counts the number of stored indices in the dataflow graph created by the pointer analysis.
     */
    private countStoredVertexIndices;
    /**
     * Counts the number of stored indices in the dataflow graph created by the pointer analysis.
     */
    private countStoredEnvIndices;
    /**
     * Counts the number of stored indices in the passed definitions.
     */
    private countStoredIndices;
    /**
     * Recursively counts the number of indices and sub-indices in the given collection.
     */
    private countIndices;
    /**
     * Slice for the given {@link SlicingCriteria}.
     * @see SingleSlicingCriterion
     *
     * @returns The per slice stats retrieved for this slicing criteria
     */
    slice(...slicingCriteria: SlicingCriteria): Promise<BenchmarkSingleSliceStats>;
    /** Bridging the gap between the new internal and the old names for the benchmarking */
    private measureCommonStep;
    private measureSliceStep;
    private guardActive;
    /**
     * Call {@link slice} for all slicing criteria that match the given filter.
     * See {@link collectAllSlicingCriteria} for details.
     * <p>
     * the `report` function will be called *before* each *individual* slice is performed.
     *
     * @returns The number of slices that were produced
     *
     * @see collectAllSlicingCriteria
     * @see SlicingCriteriaFilter
     */
    sliceForAll(filter: SlicingCriteriaFilter, report?: (current: number, total: number, allCriteria: SlicingCriteria[]) => void, options?: {
        sampleCount?: number;
        maxSliceCount?: number;
        sampleStrategy?: SamplingStrategy;
    }): Promise<number>;
    /**
     * Retrieves the final stats and closes the shell session.
     * Can be called multiple times to retrieve the stored stats, but will only close the session once (the first time).
     */
    finish(): BenchmarkSlicerStats;
    /**
     * Only call in case of an error - if the session must be closed and the benchmark itself is to be considered failed/dead.
     */
    ensureSessionClosed(): void;
}