H-3330: Optimize allocation behavior during report construction

[indietyp]

🌟 What is the purpose of this PR?

This optimizes the allocation behavior of a report by introducing a backing vector.

This is an experimental change and might not be merged into error-stack!

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies a Cargo-publishable library, but it is not yet ready to publish

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

[codecov]

Codecov Report

Attention: Patch coverage is 79.73568% with 46 lines in your changes missing coverage. Please review.

Please upload report for BASE (main@24d46d2). Learn more about missing BASE report.
Report is 2361 commits behind head on main.

Files with missing lines	Patch %	Lines
libs/error-stack/src/report/impl.rs	87.76%	17 Missing ⚠️
libs/error-stack/src/report/mod.rs	70.73%	12 Missing ⚠️
libs/error-stack/src/frame/frame_impl.rs	71.42%	6 Missing ⚠️
libs/error-stack/src/frame/mod.rs	60.00%	6 Missing ⚠️
libs/error-stack/src/iter.rs	40.00%	3 Missing ⚠️
libs/error-stack/src/compat/anyhow.rs	0.00%	1 Missing ⚠️
libs/error-stack/src/compat/eyre.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5161   +/-   ##
=======================================
  Coverage        ?   19.42%           
=======================================
  Files           ?      508           
  Lines           ?    17126           
  Branches        ?     2546           
=======================================
  Hits            ?     3327           
  Misses          ?    13787           
  Partials        ?       12           

Flag	Coverage Δ
rust.error-stack	70.89% <79.73%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Benchmark results

@rust/graph-benches – Integrations

scaling_read_entity_complete_one_depth

Function	Value	Mean	Flame graphs
entity_by_id	10 entities	$$52.6 \mathrm{ms} \pm 111 \mathrm{μs}\left({\color{gray}-2.726 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	50 entities	$$278 \mathrm{ms} \pm 1.77 \mathrm{ms}\left({\color{lightgreen}-31.223 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1 entities	$$20.4 \mathrm{ms} \pm 132 \mathrm{μs}\left({\color{gray}0.473 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	25 entities	$$76.2 \mathrm{ms} \pm 466 \mathrm{μs}\left({\color{gray}2.96 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	5 entities	$$25.7 \mathrm{ms} \pm 196 \mathrm{μs}\left({\color{gray}1.66 \mathrm{\%}}\right) $$	Flame Graph

scaling_read_entity_complete_zero_depth

Function	Value	Mean	Flame graphs
entity_by_id	10 entities	$$2.07 \mathrm{ms} \pm 17.2 \mathrm{μs}\left({\color{gray}-0.892 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	50 entities	$$4.05 \mathrm{ms} \pm 22.9 \mathrm{μs}\left({\color{gray}-0.103 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1 entities	$$1.93 \mathrm{ms} \pm 9.98 \mathrm{μs}\left({\color{gray}2.21 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	25 entities	$$3.18 \mathrm{ms} \pm 11.4 \mathrm{μs}\left({\color{red}9.28 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	5 entities	$$1.92 \mathrm{ms} \pm 9.48 \mathrm{μs}\left({\color{gray}-0.746 \mathrm{\%}}\right) $$	Flame Graph

scaling_read_entity_linkless

Function	Value	Mean	Flame graphs
entity_by_id	10 entities	$$1.88 \mathrm{ms} \pm 5.83 \mathrm{μs}\left({\color{gray}-0.563 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	100 entities	$$2.04 \mathrm{ms} \pm 9.22 \mathrm{μs}\left({\color{gray}-0.034 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1000 entities	$$2.87 \mathrm{ms} \pm 17.1 \mathrm{μs}\left({\color{lightgreen}-20.318 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1 entities	$$1.87 \mathrm{ms} \pm 5.76 \mathrm{μs}\left({\color{gray}-1.141 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10000 entities	$$13.3 \mathrm{ms} \pm 132 \mathrm{μs}\left({\color{gray}3.20 \mathrm{\%}}\right) $$	Flame Graph

representative_read_entity_type

Function	Value	Mean	Flame graphs
get_entity_type_by_id	Account ID: d4e16033-c281-4cde-aa35-9085bf2e7579	$$1.42 \mathrm{ms} \pm 6.81 \mathrm{μs}\left({\color{gray}0.450 \mathrm{\%}}\right) $$	Flame Graph

representative_read_entity

Function	Value	Mean	Flame graphs
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/song/v/1	$$16.5 \mathrm{ms} \pm 171 \mathrm{μs}\left({\color{gray}1.69 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/block/v/1	$$15.9 \mathrm{ms} \pm 171 \mathrm{μs}\left({\color{gray}-1.363 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/book/v/1	$$15.6 \mathrm{ms} \pm 145 \mathrm{μs}\left({\color{lightgreen}-5.238 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/page/v/2	$$15.4 \mathrm{ms} \pm 189 \mathrm{μs}\left({\color{gray}0.800 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/person/v/1	$$15.2 \mathrm{ms} \pm 159 \mathrm{μs}\left({\color{gray}-0.983 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/uk-address/v/1	$$15.8 \mathrm{ms} \pm 169 \mathrm{μs}\left({\color{lightgreen}-10.470 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/playlist/v/1	$$15.3 \mathrm{ms} \pm 172 \mathrm{μs}\left({\color{gray}-2.954 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/building/v/1	$$16.6 \mathrm{ms} \pm 185 \mathrm{μs}\left({\color{lightgreen}-29.196 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/organization/v/1	$$16.0 \mathrm{ms} \pm 182 \mathrm{μs}\left({\color{gray}0.317 \mathrm{\%}}\right) $$	Flame Graph

representative_read_multiple_entities

Function	Value	Mean	Flame graphs
link_by_source_by_property	depths: DT=2, PT=2, ET=2, E=2	$$99.4 \mathrm{ms} \pm 694 \mathrm{μs}\left({\color{gray}1.71 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=0, ET=0, E=2	$$80.3 \mathrm{ms} \pm 623 \mathrm{μs}\left({\color{gray}2.70 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=0, ET=0, E=0	$$42.2 \mathrm{ms} \pm 447 \mathrm{μs}\left({\color{gray}-0.457 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=0, ET=2, E=2	$$90.7 \mathrm{ms} \pm 742 \mathrm{μs}\left({\color{gray}1.19 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=2, ET=2, E=2	$$95.4 \mathrm{ms} \pm 811 \mathrm{μs}\left({\color{gray}1.60 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=255, PT=255, ET=255, E=255	$$105 \mathrm{ms} \pm 522 \mathrm{μs}\left({\color{gray}0.430 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=2, PT=2, ET=2, E=2	$$60.6 \mathrm{ms} \pm 285 \mathrm{μs}\left({\color{gray}2.43 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=0, ET=0, E=2	$$44.4 \mathrm{ms} \pm 182 \mathrm{μs}\left({\color{gray}-1.577 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=0, ET=0, E=0	$$41.3 \mathrm{ms} \pm 284 \mathrm{μs}\left({\color{gray}4.99 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=0, ET=2, E=2	$$52.0 \mathrm{ms} \pm 301 \mathrm{μs}\left({\color{gray}1.74 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=2, ET=2, E=2	$$56.0 \mathrm{ms} \pm 245 \mathrm{μs}\left({\color{gray}3.91 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=255, PT=255, ET=255, E=255	$$66.4 \mathrm{ms} \pm 291 \mathrm{μs}\left({\color{gray}1.23 \mathrm{\%}}\right) $$	Flame Graph

[indietyp]

putting in draft for now as a consideration for additional future changes.

[hashdotai]

This PR introduces significant optimizations to error-stack's allocation behavior by implementing a backing vector approach. The changes look well-thought-out and should lead to improved performance when creating large error reports.

The main improvements include:

1. Reduced allocations: By using a fragment-based approach with a backing vector, the implementation can avoid frequent reallocations when building up error reports.

2. Smart memory management: The use of RawSlice and the fragment capacity doubling strategy should lead to more efficient memory usage patterns.

3. Unsized frames: Making Frame unsized and only accessible through references provides stronger guarantees about how frames are allocated and managed.

While the implementation is generally sound, I have some concerns about the safety of mutable slices and how errors are handled in some parts of the code. Additionally, some of the comments could be clearer to help future maintainers understand the design decisions.

Overall, this is a valuable optimization that should improve performance, but a few details could be refined to make the code more robust and maintainable.

[hashdotai]

The as_slice_mut method is returning a mutable reference to memory that could potentially be referenced elsewhere. Consider adding documentation that explains why this is safe, specifically about the ownership model that prevents aliasing.

[hashdotai]

The append function could be improved with better error handling. Instead of returning T on error, consider returning a Result<RawSlice, InsertionError> where InsertionError contains the original frames. This makes the error path more explicit and follows Rust's error handling patterns.

[hashdotai]

The INITIAL_FRAGMENT_CAPACITY constant is a good start for tuning, but it might be worth making this configurable via a feature flag or build-time configuration, especially if this is an experimental optimization that might be benchmarked with different values.

[hashdotai]

The comment about "front loading" fragments is a bit confusing. Consider clarifying this with more detailed explanation about the memory layout implications of this approach and why it improves performance.

[hashdotai]

These two calls to layer should be combined into a single layer operation for clarity, or at least have a comment explaining why they're separated. Typically when we add a context and a location, they should be bundled together as a single unit.

[Copilot]

Pull Request Overview

This PR refactors report construction by replacing the previous vector‐based frame storage with a backing ReportImpl that optimizes allocation behavior while introducing unsized Frame types. Key changes include updating source types from Frame to Box, reworking report creation and frame attachment methods, and adding a new internal module for allocation logic.

Reviewed Changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/snapshots/doc/report_debug__doc.snap	Updated file paths in error snapshots for consistency with new module structure
src/serde.rs	Changed signatures in SerializeContext and SerializeSources to use Box instead of Frame
src/report/mod.rs	Updated report API to use ReportImpl via unsized Frame types; adjusted functions such as from_frame, push, and append
src/report/impl.rs	Introduced ReportImpl abstraction for improved allocation and frame fragment management
src/iter.rs	Adjusted iterator types to iterate over Box
src/hook/context.rs, src/frame/mod.rs, src/frame/frame_impl.rs	Updated generics and refactored Frame implementation to support unsized Frames
src/fmt and compat/*	Updated related APIs and documentation to align with the new Frame model

Comments suppressed due to low confidence (2)

libs/error-stack/src/report/mod.rs:814

• Consider adding a comment that clarifies the ownership transfer when calling 'self.inner.union(*report.inner)' to help future maintainers understand that the inner report is consumed.

    pub fn push(&mut self, report: Report<C>) {

libs/error-stack/src/report/mod.rs:308

• Update the function documentation for 'from_frame' to explain the change to using 'impl FrameImpl' and the impact on report construction with unsized Frames.

    pub(crate) fn from_frame(frame: impl FrameImpl) -> Self {