Skip to main content

Inferer

Struct Inferer 

Source
pub struct Inferer { /* private fields */ }
Expand description

A reusable class-file type inferer.

An inferer owns an InferenceConfig and can analyze more than one class file with it.

Implementations§

Source§

impl Inferer

Source

pub fn new(config: InferenceConfig) -> Result<Self, Error>

Creates an inferer using config.

Returns Error::InvalidConfiguration when either configured limit is zero.

Examples found in repository?
examples/infer_jrt.rs (line 20)
8fn main() -> Result<(), Box<dyn Error>> {
9    let arguments = env::args_os().skip(1).collect::<Vec<_>>();
10    if arguments.len() != 2 {
11        return Err("usage: cargo run --example infer_jrt -- <class-or-jar> <jdk-java-executable> (JDK 11+)".into());
12    }
13    let classes = read_classes(Path::new(&arguments[0]))?;
14    let mut input_hierarchy = ClassHierarchy::new();
15    for bytes in &classes {
16        input_hierarchy.insert_class(bytes)?;
17    }
18    let without_config =
19        InferenceConfig::default().with_shared_type_hierarchy(Arc::new(input_hierarchy));
20    let without_jrt = Inferer::new(without_config)?.infer_classes(&classes)?;
21    eprintln!("Reading jrt:/ from the selected JDK; target classes are never executed.");
22    let export = Command::new(&arguments[1])
23        .arg(concat!(
24            env!("CARGO_MANIFEST_DIR"),
25            "/examples/support/ExportJrt.java"
26        ))
27        .output()?;
28    if !export.status.success() {
29        return Err(format!(
30            "jrt export failed: {}",
31            String::from_utf8_lossy(&export.stderr)
32        )
33        .into());
34    }
35    let mut hierarchy = ClassHierarchy::new();
36    let reference_count = hierarchy.insert_jar(&export.stdout)?;
37    drop(export);
38    for bytes in &classes {
39        hierarchy.insert_class(bytes)?;
40    }
41    let config = InferenceConfig::default().with_shared_type_hierarchy(Arc::new(hierarchy));
42    let with_jrt = Inferer::new(config)?.infer_classes(&classes)?;
43    println!("JDK reference classes: {reference_count}");
44    println!("Both modes index the input class headers; only the second adds jrt.");
45    comparison::report("without jrt", &without_jrt);
46    comparison::report("with jrt", &with_jrt);
47    comparison::compare(&without_jrt, &with_jrt);
48    if !without_jrt.analysis_complete() || !with_jrt.analysis_complete() {
49        return Err("analysis did not reach a fixed point".into());
50    }
51    Ok(())
52}
More examples
Hide additional examples
examples/infer.rs (line 31)
5fn main() -> ExitCode {
6    let mut arguments = env::args_os().skip(1);
7    let Some(path) = arguments.next() else {
8        eprintln!("usage: cargo run --example infer -- <class-file> [--reference <jar>]...");
9        return ExitCode::FAILURE;
10    };
11
12    let mut hierarchy = ClassHierarchy::new();
13    while let Some(option) = arguments.next() {
14        if option != "--reference" {
15            eprintln!("unknown option: {}", option.to_string_lossy());
16            return ExitCode::FAILURE;
17        }
18        let Some(reference) = arguments.next() else {
19            eprintln!("--reference requires a JAR path");
20            return ExitCode::FAILURE;
21        };
22        if let Err(error) = hierarchy.insert_jar_file(&reference) {
23            eprintln!("failed to index {}: {error}", reference.to_string_lossy());
24            return ExitCode::FAILURE;
25        }
26    }
27    let mut config = InferenceConfig::default();
28    if !hierarchy.is_empty() {
29        config = config.with_shared_type_hierarchy(Arc::new(hierarchy));
30    }
31    let inferer = match Inferer::new(config) {
32        Ok(inferer) => inferer,
33        Err(error) => {
34            eprintln!("failed to configure inference: {error}");
35            return ExitCode::FAILURE;
36        }
37    };
38
39    let path = Path::new(&path);
40    let bytes = match fs::read(path) {
41        Ok(bytes) => bytes,
42        Err(error) => {
43            eprintln!("failed to read {}: {error}", path.display());
44            return ExitCode::FAILURE;
45        }
46    };
47
48    let inference = match inferer.infer_class(&bytes) {
49        Ok(inference) => inference,
50        Err(error) => {
51            eprintln!("failed to infer {}: {error}", path.display());
52            return ExitCode::FAILURE;
53        }
54    };
55
56    println!("class: {}", inference.class_name().as_str());
57    println!("analysis complete: {}", inference.analysis_complete());
58
59    for method in inference.methods() {
60        println!("\nmethod: {}", method.name());
61        println!("  descriptor: {:?}", method.descriptor());
62        println!("  declared return type: {:?}", method.return_type());
63        println!(
64            "  inferred return type: {:?}",
65            method.inferred_return_type()
66        );
67        println!(
68            "  returned parameter index: {:?}",
69            method.returned_parameter_index()
70        );
71        println!("  analysis complete: {}", method.analysis_complete());
72        println!("  local types:");
73
74        for (slot, inferred_type) in method.local_types().iter().enumerate() {
75            println!("    {slot}: {inferred_type:?}");
76        }
77
78        for instruction in method.instructions() {
79            if instruction.operand_expectations().is_empty() {
80                continue;
81            }
82            println!(
83                "  operand expectations at {}:",
84                instruction.bytecode_offset()
85            );
86            for expectation in instruction.operand_expectations() {
87                println!(
88                    "    stack[{}]: {:?}",
89                    expectation.stack_index(),
90                    expectation.constraint()
91                );
92            }
93        }
94    }
95
96    if inference.diagnostics().is_empty() {
97        println!("\ndiagnostics: none");
98    } else {
99        println!("\ndiagnostics:");
100        for diagnostic in inference.diagnostics() {
101            let location = diagnostic.location();
102            println!(
103                "  {:?} {:?}: {}",
104                diagnostic.severity(),
105                diagnostic.kind(),
106                diagnostic.message()
107            );
108
109            if let Some(method_name) = location.method_name() {
110                println!(
111                    "    method: {}{}",
112                    method_name,
113                    location.method_descriptor().unwrap_or_default()
114                );
115            }
116            if let Some(offset) = location.bytecode_offset() {
117                println!("    bytecode offset: {offset}");
118            }
119        }
120    }
121
122    ExitCode::SUCCESS
123}
Source

pub const fn config(&self) -> &InferenceConfig

Returns this inferer’s analysis configuration.

Source

pub fn infer_class(&self, bytes: &[u8]) -> Result<ClassInference, Error>

Infers types from one complete Java class file.

The analysis works from the supplied class-file bytes and does not load JDK symbols or resolve an external class hierarchy. StackMapTable is ignored so missing or forged verification frames cannot affect results.

Examples found in repository?
examples/infer.rs (line 48)
5fn main() -> ExitCode {
6    let mut arguments = env::args_os().skip(1);
7    let Some(path) = arguments.next() else {
8        eprintln!("usage: cargo run --example infer -- <class-file> [--reference <jar>]...");
9        return ExitCode::FAILURE;
10    };
11
12    let mut hierarchy = ClassHierarchy::new();
13    while let Some(option) = arguments.next() {
14        if option != "--reference" {
15            eprintln!("unknown option: {}", option.to_string_lossy());
16            return ExitCode::FAILURE;
17        }
18        let Some(reference) = arguments.next() else {
19            eprintln!("--reference requires a JAR path");
20            return ExitCode::FAILURE;
21        };
22        if let Err(error) = hierarchy.insert_jar_file(&reference) {
23            eprintln!("failed to index {}: {error}", reference.to_string_lossy());
24            return ExitCode::FAILURE;
25        }
26    }
27    let mut config = InferenceConfig::default();
28    if !hierarchy.is_empty() {
29        config = config.with_shared_type_hierarchy(Arc::new(hierarchy));
30    }
31    let inferer = match Inferer::new(config) {
32        Ok(inferer) => inferer,
33        Err(error) => {
34            eprintln!("failed to configure inference: {error}");
35            return ExitCode::FAILURE;
36        }
37    };
38
39    let path = Path::new(&path);
40    let bytes = match fs::read(path) {
41        Ok(bytes) => bytes,
42        Err(error) => {
43            eprintln!("failed to read {}: {error}", path.display());
44            return ExitCode::FAILURE;
45        }
46    };
47
48    let inference = match inferer.infer_class(&bytes) {
49        Ok(inference) => inference,
50        Err(error) => {
51            eprintln!("failed to infer {}: {error}", path.display());
52            return ExitCode::FAILURE;
53        }
54    };
55
56    println!("class: {}", inference.class_name().as_str());
57    println!("analysis complete: {}", inference.analysis_complete());
58
59    for method in inference.methods() {
60        println!("\nmethod: {}", method.name());
61        println!("  descriptor: {:?}", method.descriptor());
62        println!("  declared return type: {:?}", method.return_type());
63        println!(
64            "  inferred return type: {:?}",
65            method.inferred_return_type()
66        );
67        println!(
68            "  returned parameter index: {:?}",
69            method.returned_parameter_index()
70        );
71        println!("  analysis complete: {}", method.analysis_complete());
72        println!("  local types:");
73
74        for (slot, inferred_type) in method.local_types().iter().enumerate() {
75            println!("    {slot}: {inferred_type:?}");
76        }
77
78        for instruction in method.instructions() {
79            if instruction.operand_expectations().is_empty() {
80                continue;
81            }
82            println!(
83                "  operand expectations at {}:",
84                instruction.bytecode_offset()
85            );
86            for expectation in instruction.operand_expectations() {
87                println!(
88                    "    stack[{}]: {:?}",
89                    expectation.stack_index(),
90                    expectation.constraint()
91                );
92            }
93        }
94    }
95
96    if inference.diagnostics().is_empty() {
97        println!("\ndiagnostics: none");
98    } else {
99        println!("\ndiagnostics:");
100        for diagnostic in inference.diagnostics() {
101            let location = diagnostic.location();
102            println!(
103                "  {:?} {:?}: {}",
104                diagnostic.severity(),
105                diagnostic.kind(),
106                diagnostic.message()
107            );
108
109            if let Some(method_name) = location.method_name() {
110                println!(
111                    "    method: {}{}",
112                    method_name,
113                    location.method_descriptor().unwrap_or_default()
114                );
115            }
116            if let Some(offset) = location.bytecode_offset() {
117                println!("    bytecode offset: {offset}");
118            }
119        }
120    }
121
122    ExitCode::SUCCESS
123}
Source

pub fn infer_classes<I, B>( &self, class_files: I, ) -> Result<ClassInferences, Error>
where I: IntoIterator<Item = B>, B: AsRef<[u8]>,

Infers types from a batch of complete Java class files.

The batch keeps its input order and rejects duplicate JVM internal class names. This method never reads a JAR, directory, class loader, JDK, or Java runtime; it only analyzes the supplied class-file bytes. Static and special calls to another class in the batch automatically consume that class’s converged return summary. Virtual calls do the same only for a final class, a final method, or a fresh allocation of the member owner. Calls without a uniquely provable target keep their descriptor-derived return type. Proven returned-parameter relations also propagate across deterministic calls, preserving argument types through chains of wrapper methods without an external runtime hierarchy.

Examples found in repository?
examples/infer_jrt.rs (line 20)
8fn main() -> Result<(), Box<dyn Error>> {
9    let arguments = env::args_os().skip(1).collect::<Vec<_>>();
10    if arguments.len() != 2 {
11        return Err("usage: cargo run --example infer_jrt -- <class-or-jar> <jdk-java-executable> (JDK 11+)".into());
12    }
13    let classes = read_classes(Path::new(&arguments[0]))?;
14    let mut input_hierarchy = ClassHierarchy::new();
15    for bytes in &classes {
16        input_hierarchy.insert_class(bytes)?;
17    }
18    let without_config =
19        InferenceConfig::default().with_shared_type_hierarchy(Arc::new(input_hierarchy));
20    let without_jrt = Inferer::new(without_config)?.infer_classes(&classes)?;
21    eprintln!("Reading jrt:/ from the selected JDK; target classes are never executed.");
22    let export = Command::new(&arguments[1])
23        .arg(concat!(
24            env!("CARGO_MANIFEST_DIR"),
25            "/examples/support/ExportJrt.java"
26        ))
27        .output()?;
28    if !export.status.success() {
29        return Err(format!(
30            "jrt export failed: {}",
31            String::from_utf8_lossy(&export.stderr)
32        )
33        .into());
34    }
35    let mut hierarchy = ClassHierarchy::new();
36    let reference_count = hierarchy.insert_jar(&export.stdout)?;
37    drop(export);
38    for bytes in &classes {
39        hierarchy.insert_class(bytes)?;
40    }
41    let config = InferenceConfig::default().with_shared_type_hierarchy(Arc::new(hierarchy));
42    let with_jrt = Inferer::new(config)?.infer_classes(&classes)?;
43    println!("JDK reference classes: {reference_count}");
44    println!("Both modes index the input class headers; only the second adds jrt.");
45    comparison::report("without jrt", &without_jrt);
46    comparison::report("with jrt", &with_jrt);
47    comparison::compare(&without_jrt, &with_jrt);
48    if !without_jrt.analysis_complete() || !with_jrt.analysis_complete() {
49        return Err("analysis did not reach a fixed point".into());
50    }
51    Ok(())
52}

Trait Implementations§

Source§

impl Clone for Inferer

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Inferer

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for Inferer

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.