Skip to content

Commit

Permalink
Replace Context::new with Loader::new (#296)
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@philipc
philipc authored May 19, 2024
1 parent ade443f commit c60b7e0
Show file tree
Hide file tree
Showing 11 changed files with 433 additions and 616 deletions.
7 changes: 4 additions & 3 deletions .github/workflows/rust.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
23 changes: 15 additions & 8 deletions Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -61,11 +68,11 @@ required-features = ["bin"]

[[test]]
name = "correctness"
required-features = ["default"]
required-features = ["loader", "fallible-iterator"]

[[test]]
name = "parse"
required-features = ["std-object"]
required-features = ["loader"]

[[bin]]
name = "addr2line"
Expand Down
34 changes: 17 additions & 17 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,25 @@
[![](https://img.shields.io/docsrs/addr2line.svg)](https://docs.rs/addr2line)
[![Coverage Status](https://coveralls.io/repos/github/gimli-rs/addr2line/badge.svg?branch=master)](https://coveralls.io/github/gimli-rs/addr2line?branch=master)

A cross-platform library for retrieving per-address debug information
from files with DWARF debug information.

`addr2line` uses [`gimli`](https://github.com/gimli-rs/gimli) to parse
the debug information, and exposes an interface for finding
the source file, line number, and wrapping function for instruction
addresses within the target program. These lookups can either be
performed programmatically through `Context::find_location` and
`Context::find_frames`, or via the included example binary,
`addr2line` (named and modelled after the equivalent utility from
[GNU binutils](https://sourceware.org/binutils/docs/binutils/addr2line.html)).
`addr2line` provides a cross-platform library for retrieving per-address debug information
from files with DWARF debug information. Given an address, it can return the file name,
line number, and function name associated with that address, as well as the inline call
stack leading to that address.

The crate has a CLI wrapper around the library which provides some of
the functionality of the `addr2line` command line tool distributed with
[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

Expand Down
145 changes: 8 additions & 137 deletions benches/bench.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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| {
Expand All @@ -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| {
Expand All @@ -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| {
Expand All @@ -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| {
Expand All @@ -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| {
Expand All @@ -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| {
Expand Down Expand Up @@ -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| {
Expand All @@ -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| {
Expand Down
Loading

0 comments on commit c60b7e0

Please sign in to comment.