Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Replace Context::new with Loader::new #296

Merged
merged 1 commit into from
May 19, 2024
Merged

Replace Context::new with Loader::new #296

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions .github/workflows/rust.yml
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading