Replace Context::new with Loader::new

The Loader encapsulates the process of loading the DWARF data and keeping it alive so that the Context can refer to it. It also handles tasks such as loading dSYM or DWO files. This allows us to remove the `object` crate from the public API.
gimli-rs · May 17, 2024 · 8d9c23d · 8d9c23d
1 parent ade443f
commit 8d9c23d
Show file tree

Hide file tree

Showing 11 changed files with 420 additions and 597 deletions.
diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
@@ -36,11 +36,11 @@ jobs:
     - name: Test debug
       run: |
         cargo test --verbose
-        cargo test --verbose --features bin
+        cargo test --verbose --features all
     - name: Test release
       run: |
         cargo test --verbose --release
-        cargo test --verbose --release --features bin
+        cargo test --verbose --release --features all
 
   features:
     runs-on: ubuntu-latest
@@ -50,10 +50,11 @@ jobs:
       - run: cargo build --no-default-features --features std
       - run: cargo build --no-default-features --features std,cpp_demangle
       - run: cargo build --no-default-features --features std,rustc-demangle
-      - run: cargo build --no-default-features --features std-object
+      - run: cargo build --no-default-features --features loader
       - run: cargo build --no-default-features --features fallible-iterator
       - run: cargo build --no-default-features --features smallvec
       - run: cargo build --no-default-features --features bin
+      - run: cargo build --no-default-features --features all
 
   bench:
     runs-on: ubuntu-latest

diff --git a/Cargo.toml b/Cargo.toml
@@ -15,15 +15,17 @@ rust-version = "1.65"
 [dependencies]
 gimli = { version = "0.29.0", default-features = false, features = ["read"] }
 fallible-iterator = { version = "0.3.0", default-features = false, optional = true }
-memmap2 = { version = "0.9.4", optional = true }
-object = { version = "0.35.0", default-features = false, features = ["read"], optional = true }
 smallvec = { version = "1", default-features = false, optional = true }
 rustc-demangle = { version = "0.1", optional = true }
 cpp_demangle = { version = "0.4", default-features = false, features = ["alloc"], optional = true }
 
+# loader dependencies
+object = { version = "0.35.0", default-features = false, features = ["read", "compression"], optional = true }
+memmap2 = { version = "0.9.4", optional = true }
+typed-arena = { version = "2", optional = true }
+
 # bin dependencies
 clap = { version = "4.3.21", features = ["wrap_help"], optional = true }
-typed-arena = { version = "2", optional = true }
 
 # Internal feature, only used when building as part of libstd, not part of the
 # stable interface of this crate.
@@ -45,10 +47,15 @@ debug = true
 codegen-units = 1
 
 [features]
-default = ["rustc-demangle", "cpp_demangle", "std-object", "fallible-iterator", "smallvec", "memmap2"]
+default = ["rustc-demangle", "cpp_demangle", "loader", "fallible-iterator", "smallvec"]
 std = ["gimli/std"]
-std-object = ["std", "object", "object/std", "object/compression", "gimli/endian-reader"]
-bin = ["default", "dep:clap", "dep:typed-arena"]
+loader = ["std", "dep:object", "dep:memmap2", "dep:typed-arena"]
+bin = ["loader", "rustc-demangle", "cpp_demangle", "smallvec", "dep:clap"]
+all = ["bin"]
+
+# Use of --all-features is not supported.
+# This is a dummy feature to detect when --all-features is used.
+cargo-all = []
 
 # Internal feature, only used when building as part of libstd, not part of the
 # stable interface of this crate.
@@ -57,15 +64,15 @@ rustc-dep-of-std = ['core', 'alloc', 'compiler_builtins', 'gimli/rustc-dep-of-st
 [[test]]
 name = "output_equivalence"
 harness = false
-required-features = ["bin"]
+required-features = ["loader"]
 
 [[test]]
 name = "correctness"
-required-features = ["default"]
+required-features = ["loader"]
 
 [[test]]
 name = "parse"
-required-features = ["std-object"]
+required-features = ["loader"]
 
 [[bin]]
 name = "addr2line"

diff --git a/README.md b/README.md
@@ -17,12 +17,15 @@ performed programmatically through `Context::find_location` and
 [GNU binutils](https://sourceware.org/binutils/docs/binutils/addr2line.html)).
 
 # Quickstart
- - Add the [`addr2line` crate](https://crates.io/crates/addr2line) to your `Cargo.toml`
- - Load the file and parse it with [`addr2line::object::read::File::parse`](https://docs.rs/object/*/object/read/struct.File.html#method.parse)
- - Pass the parsed file to [`addr2line::Context::new` ](https://docs.rs/addr2line/*/addr2line/struct.Context.html#method.new)
- - Use [`addr2line::Context::find_location`](https://docs.rs/addr2line/*/addr2line/struct.Context.html#method.find_location)
-   or [`addr2line::Context::find_frames`](https://docs.rs/addr2line/*/addr2line/struct.Context.html#method.find_frames)
-   to look up debug information for an address
+ - Add the [`addr2line` crate](https://crates.io/crates/addr2line) to your `Cargo.toml`.
+ - Call [`addr2line::Loader::new`](https://docs.rs/addr2line/*/addr2line/struct.Loader.html#method.new) with the file path.
+ - Use [`addr2line::Loader::find_location`](https://docs.rs/addr2line/*/addr2line/struct.Loader.html#method.find_location)
+   or [`addr2line::Loader::find_frames`](https://docs.rs/addr2line/*/addr2line/struct.Loader.html#method.find_frames)
+   to look up debug information for an address.
+
+If you want to provide your own file loading and memory management, use
+[`addr2line::Context`](https://docs.rs/addr2line/*/addr2line/struct.Context.html)
+instead of `addr2line::Loader`.
 
 # Performance
 

diff --git a/benches/bench.rs b/benches/bench.rs
@@ -66,18 +66,7 @@ fn get_test_addresses(target: &object::File<'_>) -> Vec<u64> {
 }
 
 #[bench]
-fn context_new_rc(b: &mut test::Bencher) {
-    let target = release_fixture_path();
-
-    with_file(&target, |file| {
-        b.iter(|| {
-            addr2line::Context::new(file).unwrap();
-        });
-    });
-}
-
-#[bench]
-fn context_new_slice(b: &mut test::Bencher) {
+fn context_new(b: &mut test::Bencher) {
     let target = release_fixture_path();
 
     with_file(&target, |file| {
@@ -90,19 +79,7 @@ fn context_new_slice(b: &mut test::Bencher) {
 }
 
 #[bench]
-fn context_new_parse_lines_rc(b: &mut test::Bencher) {
-    let target = release_fixture_path();
-
-    with_file(&target, |file| {
-        b.iter(|| {
-            let context = addr2line::Context::new(file).unwrap();
-            context.parse_lines().unwrap();
-        });
-    });
-}
-
-#[bench]
-fn context_new_parse_lines_slice(b: &mut test::Bencher) {
+fn context_new_parse_lines(b: &mut test::Bencher) {
     let target = release_fixture_path();
 
     with_file(&target, |file| {
@@ -116,19 +93,7 @@ fn context_new_parse_lines_slice(b: &mut test::Bencher) {
 }
 
 #[bench]
-fn context_new_parse_functions_rc(b: &mut test::Bencher) {
-    let target = release_fixture_path();
-
-    with_file(&target, |file| {
-        b.iter(|| {
-            let context = addr2line::Context::new(file).unwrap();
-            context.parse_functions().unwrap();
-        });
-    });
-}
-
-#[bench]
-fn context_new_parse_functions_slice(b: &mut test::Bencher) {
+fn context_new_parse_functions(b: &mut test::Bencher) {
     let target = release_fixture_path();
 
     with_file(&target, |file| {
@@ -142,19 +107,7 @@ fn context_new_parse_functions_slice(b: &mut test::Bencher) {
 }
 
 #[bench]
-fn context_new_parse_inlined_functions_rc(b: &mut test::Bencher) {
-    let target = release_fixture_path();
-
-    with_file(&target, |file| {
-        b.iter(|| {
-            let context = addr2line::Context::new(file).unwrap();
-            context.parse_inlined_functions().unwrap();
-        });
-    });
-}
-
-#[bench]
-fn context_new_parse_inlined_functions_slice(b: &mut test::Bencher) {
+fn context_new_parse_inlined_functions(b: &mut test::Bencher) {
     let target = release_fixture_path();
 
     with_file(&target, |file| {
@@ -168,28 +121,7 @@ fn context_new_parse_inlined_functions_slice(b: &mut test::Bencher) {
 }
 
 #[bench]
-fn context_query_location_rc(b: &mut test::Bencher) {
-    let target = release_fixture_path();
-
-    with_file(&target, |file| {
-        let addresses = get_test_addresses(file);
-
-        let ctx = addr2line::Context::new(file).unwrap();
-        // Ensure nothing is lazily loaded.
-        for addr in &addresses {
-            test::black_box(ctx.find_location(*addr)).ok();
-        }
-
-        b.iter(|| {
-            for addr in &addresses {
-                test::black_box(ctx.find_location(*addr)).ok();
-            }
-        });
-    });
-}
-
-#[bench]
-fn context_query_location_slice(b: &mut test::Bencher) {
+fn context_query_location(b: &mut test::Bencher) {
     let target = release_fixture_path();
 
     with_file(&target, |file| {
@@ -212,34 +144,7 @@ fn context_query_location_slice(b: &mut test::Bencher) {
 }
 
 #[bench]
-fn context_query_with_functions_rc(b: &mut test::Bencher) {
-    let target = release_fixture_path();
-
-    with_file(&target, |file| {
-        let addresses = get_test_addresses(file);
-
-        let ctx = addr2line::Context::new(file).unwrap();
-        // Ensure nothing is lazily loaded.
-        for addr in &addresses {
-            let mut frames = ctx.find_frames(*addr).skip_all_loads().unwrap();
-            while let Ok(Some(ref frame)) = frames.next() {
-                test::black_box(frame);
-            }
-        }
-
-        b.iter(|| {
-            for addr in &addresses {
-                let mut frames = ctx.find_frames(*addr).skip_all_loads().unwrap();
-                while let Ok(Some(ref frame)) = frames.next() {
-                    test::black_box(frame);
-                }
-            }
-        });
-    });
-}
-
-#[bench]
-fn context_query_with_functions_slice(b: &mut test::Bencher) {
+fn context_query_with_functions(b: &mut test::Bencher) {
     let target = release_fixture_path();
 
     with_file(&target, |file| {
@@ -268,23 +173,7 @@ fn context_query_with_functions_slice(b: &mut test::Bencher) {
 }
 
 #[bench]
-fn context_new_and_query_location_rc(b: &mut test::Bencher) {
-    let target = release_fixture_path();
-
-    with_file(&target, |file| {
-        let addresses = get_test_addresses(file);
-
-        b.iter(|| {
-            let ctx = addr2line::Context::new(file).unwrap();
-            for addr in addresses.iter().take(100) {
-                test::black_box(ctx.find_location(*addr)).ok();
-            }
-        });
-    });
-}
-
-#[bench]
-fn context_new_and_query_location_slice(b: &mut test::Bencher) {
+fn context_new_and_query_location(b: &mut test::Bencher) {
     let target = release_fixture_path();
 
     with_file(&target, |file| {
@@ -302,25 +191,7 @@ fn context_new_and_query_location_slice(b: &mut test::Bencher) {
 }
 
 #[bench]
-fn context_new_and_query_with_functions_rc(b: &mut test::Bencher) {
-    let target = release_fixture_path();
-
-    with_file(&target, |file| {
-        let addresses = get_test_addresses(file);
-
-        b.iter(|| {
-            let ctx = addr2line::Context::new(file).unwrap();
-            for addr in addresses.iter().take(100) {
-                let mut frames = ctx.find_frames(*addr).skip_all_loads().unwrap();
-                while let Ok(Some(ref frame)) = frames.next() {
-                    test::black_box(frame);
-                }
-            }
-        });
-    });
-}
-#[bench]
-fn context_new_and_query_with_functions_slice(b: &mut test::Bencher) {
+fn context_new_and_query_with_functions(b: &mut test::Bencher) {
     let target = release_fixture_path();
 
     with_file(&target, |file| {