From 2727f10b216fc6ac7d3a22f216f55e46e9c99506 Mon Sep 17 00:00:00 2001 From: Dylan MacKenzie Date: Tue, 14 Jan 2020 14:52:54 -0800 Subject: [PATCH] Improve docs for new framework --- src/librustc_mir/dataflow/generic/mod.rs | 38 ++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/src/librustc_mir/dataflow/generic/mod.rs b/src/librustc_mir/dataflow/generic/mod.rs index a80e7375482..bf18bc7a5d0 100644 --- a/src/librustc_mir/dataflow/generic/mod.rs +++ b/src/librustc_mir/dataflow/generic/mod.rs @@ -1,4 +1,36 @@ -//! A framework for expressing dataflow problems. +//! A framework that can express both [gen-kill] and generic dataflow problems. +//! +//! There is another interface for dataflow in the compiler in `librustc_mir/dataflow/mod.rs`. The +//! interface in this module will eventually [replace that one][design-meeting]. +//! +//! To actually use this framework, you must implement either the `Analysis` or the +//! `GenKillAnalysis` trait. If your transfer function can be expressed with only gen/kill +//! operations, prefer `GenKillAnalysis` as it will perform better. Create an `Engine` using the +//! appropriate constructor and call `iterate_to_fixpoint`. You can use a `ResultsCursor` to +//! inspect the fixpoint solution to your dataflow problem. +//! +//! ```ignore(cross-crate-imports) +//! fn do_my_analysis(tcx: TyCtxt<'tcx>, body: &mir::Body<'tcx>, did: DefId) { +//! let analysis = MyAnalysis::new(); +//! +//! // If `MyAnalysis` implements `GenKillAnalysis`. +//! let results = Engine::new_gen_kill(tcx, body, did, analysis).iterate_to_fixpoint(); +//! +//! // If `MyAnalysis` implements `Analysis`. +//! // let results = Engine::new_generic(tcx, body, did, analysis).iterate_to_fixpoint(); +//! +//! let mut cursor = ResultsCursor::new(body, results); +//! +//! for (_, statement_index) in body.block_data[START_BLOCK].statements.iter_enumerated() { +//! cursor.seek_after(Location { block: START_BLOCK, statement_index }); +//! let state = cursor.get(); +//! println!("{:?}", state); +//! } +//! } +//! ``` +//! +//! [gen-kill]: https://en.wikipedia.org/wiki/Data-flow_analysis#Bit_vector_problems +//! [design-meeting]https://github.com/rust-lang/compiler-team/issues/202 use std::io; @@ -68,7 +100,7 @@ fn pretty_print_idx(&self, w: &mut impl io::Write, idx: Self::Idx) -> io::Result } } -/// Define a dataflow problem with an arbitrarily complex transfer function. +/// A dataflow problem with an arbitrarily complex transfer function. pub trait Analysis<'tcx>: AnalysisDomain<'tcx> { /// Updates the current dataflow state with the effect of evaluating a statement. fn apply_statement_effect( @@ -134,7 +166,7 @@ fn apply_call_return_effect( ); } -/// Define a gen/kill dataflow problem. +/// A gen/kill dataflow problem. /// /// Each method in this trait has a corresponding one in `Analysis`. However, these methods only /// allow modification of the dataflow state via "gen" and "kill" operations. By defining transfer -- 2.44.0