Trait rustc_mir::dataflow::framework::Analysis

pub trait Analysis<'tcx>: AnalysisDomain<'tcx> {
    fn apply_statement_effect(
        &self, 
        state: &mut Self::Domain, 
        statement: &Statement<'tcx>, 
        location: Location
    );
    fn apply_terminator_effect(
        &self, 
        state: &mut Self::Domain, 
        terminator: &Terminator<'tcx>, 
        location: Location
    );
    fn apply_call_return_effect(
        &self, 
        state: &mut Self::Domain, 
        block: BasicBlock, 
        func: &Operand<'tcx>, 
        args: &[Operand<'tcx>], 
        return_place: Place<'tcx>
    );

    fn apply_before_statement_effect(
        &self, 
        _state: &mut Self::Domain, 
        _statement: &Statement<'tcx>, 
        _location: Location
    ) { ... }
    fn apply_before_terminator_effect(
        &self, 
        _state: &mut Self::Domain, 
        _terminator: &Terminator<'tcx>, 
        _location: Location
    ) { ... }
    fn apply_yield_resume_effect(
        &self, 
        _state: &mut Self::Domain, 
        _resume_block: BasicBlock, 
        _resume_place: Place<'tcx>
    ) { ... }
    fn apply_discriminant_switch_effect(
        &self, 
        _state: &mut Self::Domain, 
        _block: BasicBlock, 
        _enum_place: Place<'tcx>, 
        _adt: &AdtDef, 
        _variant: VariantIdx
    ) { ... }
    fn into_engine<'mir>(
        self, 
        tcx: TyCtxt<'tcx>, 
        body: &'mir Body<'tcx>, 
        def_id: DefId
    ) -> Engine<'mir, 'tcx, Self>
    where
        Self: Sized,
    { ... }
}

A dataflow problem with an arbitrarily complex transfer function.

Convergence

When implementing this trait directly (not via GenKillAnalysis), it's possible to choose a transfer function such that the analysis does not reach fixpoint. To guarantee convergence, your transfer functions must maintain the following invariant:

If the dataflow state before some point in the program changes to be greater than the prior state before that point, the dataflow state after that point must also change to be greater than the prior state after that point.

This invariant guarantees that the dataflow state at a given point in the program increases monotonically until fixpoint is reached. Note that this monotonicity requirement only applies to the same point in the program at different points in time. The dataflow state at a given point in the program may or may not be greater than the state at any preceding point.

Required methods

fn apply_statement_effect(
    &self,
    state: &mut Self::Domain,
    statement: &Statement<'tcx>,
    location: Location
)

Updates the current dataflow state with the effect of evaluating a statement.

fn apply_terminator_effect(
    &self,
    state: &mut Self::Domain,
    terminator: &Terminator<'tcx>,
    location: Location
)

Updates the current dataflow state with the effect of evaluating a terminator.

The effect of a successful return from a Call terminator should not be accounted for in this function. That should go in apply_call_return_effect. For example, in the InitializedPlaces analyses, the return place for a function call is not marked as initialized here.

fn apply_call_return_effect(
    &self,
    state: &mut Self::Domain,
    block: BasicBlock,
    func: &Operand<'tcx>,
    args: &[Operand<'tcx>],
    return_place: Place<'tcx>
)

Updates the current dataflow state with the effect of a successful return from a Call terminator.

This is separate from apply_terminator_effect to properly track state across unwind edges.

Loading content...

Provided methods

fn apply_before_statement_effect(
    &self,
    _state: &mut Self::Domain,
    _statement: &Statement<'tcx>,
    _location: Location
)

Updates the current dataflow state with an effect that occurs immediately before the given statement.

This method is useful if the consumer of the results of this analysis needs only to observe part of the effect of a statement (e.g. for two-phase borrows). As a general rule, analyses should not implement this without implementing apply_statement_effect.

fn apply_before_terminator_effect(
    &self,
    _state: &mut Self::Domain,
    _terminator: &Terminator<'tcx>,
    _location: Location
)

Updates the current dataflow state with an effect that occurs immediately before the given terminator.

This method is useful if the consumer of the results of this analysis needs only to observe part of the effect of a terminator (e.g. for two-phase borrows). As a general rule, analyses should not implement this without implementing apply_terminator_effect.

fn apply_yield_resume_effect(
    &self,
    _state: &mut Self::Domain,
    _resume_block: BasicBlock,
    _resume_place: Place<'tcx>
)

Updates the current dataflow state with the effect of resuming from a Yield terminator.

This is similar to apply_call_return_effect in that it only takes place after the generator is resumed, not when it is dropped.

By default, no effects happen.

fn apply_discriminant_switch_effect(
    &self,
    _state: &mut Self::Domain,
    _block: BasicBlock,
    _enum_place: Place<'tcx>,
    _adt: &AdtDef,
    _variant: VariantIdx
)

Updates the current dataflow state with the effect of taking a particular branch in a SwitchInt terminator.

Much like apply_call_return_effect, this effect is only propagated along a single outgoing edge from this basic block.

FIXME: This class of effects is not supported for backward dataflow analyses.

fn into_engine<'mir>(
    self,
    tcx: TyCtxt<'tcx>,
    body: &'mir Body<'tcx>,
    def_id: DefId
) -> Engine<'mir, 'tcx, Self> where
    Self: Sized, 

Creates an Engine to find the fixpoint for this dataflow problem.

You shouldn't need to override this outside this module, since the combination of the default impl and the one for all A: GenKillAnalysis will do the right thing. Its purpose is to enable method chaining like so:

let results = MyAnalysis::new(tcx, body)
    .into_engine(tcx, body, def_id)
    .iterate_to_fixpoint()
    .into_results_cursor(body);

Loading content...

Implementors

impl<A, 'tcx> Analysis<'tcx> for A where
    A: GenKillAnalysis<'tcx>,
    A::Domain: GenKill<A::Idx> + BorrowMut<BitSet<A::Idx>>, 

fn apply_statement_effect(
    &self,
    state: &mut A::Domain,
    statement: &Statement<'tcx>,
    location: Location
)

fn apply_before_statement_effect(
    &self,
    state: &mut A::Domain,
    statement: &Statement<'tcx>,
    location: Location
)

fn apply_terminator_effect(
    &self,
    state: &mut A::Domain,
    terminator: &Terminator<'tcx>,
    location: Location
)

fn apply_before_terminator_effect(
    &self,
    state: &mut A::Domain,
    terminator: &Terminator<'tcx>,
    location: Location
)

fn apply_call_return_effect(
    &self,
    state: &mut A::Domain,
    block: BasicBlock,
    func: &Operand<'tcx>,
    args: &[Operand<'tcx>],
    return_place: Place<'tcx>
)

fn apply_yield_resume_effect(
    &self,
    state: &mut A::Domain,
    resume_block: BasicBlock,
    resume_place: Place<'tcx>
)

fn apply_discriminant_switch_effect(
    &self,
    state: &mut A::Domain,
    block: BasicBlock,
    enum_place: Place<'tcx>,
    adt: &AdtDef,
    variant: VariantIdx
)

fn into_engine<'mir>(
    self,
    tcx: TyCtxt<'tcx>,
    body: &'mir Body<'tcx>,
    def_id: DefId
) -> Engine<'mir, 'tcx, Self> where
    Self: Sized, 

impl<Q, 'tcx, '_, '_> Analysis<'tcx> for FlowSensitiveAnalysis<'_, '_, 'tcx, Q> where
    Q: Qualif, 

fn apply_statement_effect(
    &self,
    state: &mut Self::Domain,
    statement: &Statement<'tcx>,
    location: Location
)

fn apply_terminator_effect(
    &self,
    state: &mut Self::Domain,
    terminator: &Terminator<'tcx>,
    location: Location
)

fn apply_call_return_effect(
    &self,
    state: &mut Self::Domain,
    block: BasicBlock,
    func: &Operand<'tcx>,
    args: &[Operand<'tcx>],
    return_place: Place<'tcx>
)

Loading content...