From 3bfe5d395c8ef1227bdbc6be1b4fc45693cef4b5 Mon Sep 17 00:00:00 2001 From: Markus Stange Date: Mon, 11 Mar 2024 15:45:04 -0400 Subject: [PATCH 1/2] Update UnwindContextStorage comments after #687. PR #687 switched `StoreOnHeap` to use a `Box` with a fixed-size array. This means that, by default, `UnwindContext` will not allocate during unwind, so the primary motivation for providing a custom `UnwindContextStorage` has changed. This commit tweaks the docs a little to better match the current state. --- src/read/cfi.rs | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/src/read/cfi.rs b/src/read/cfi.rs index 9e0bc75d..1320b5b3 100644 --- a/src/read/cfi.rs +++ b/src/read/cfi.rs @@ -1867,12 +1867,22 @@ impl FrameDescriptionEntry { feature = "read", doc = " Normally you would only need to use [`StoreOnHeap`], which places the stack -on the heap using [`Vec`]. This is the default storage type parameter for [`UnwindContext`]. +on the heap using [`Box`]. This is the default storage type parameter for [`UnwindContext`]. + +You may want to supply your own storage type for one of the following reasons: + + 1. In rare cases you may run into failed unwinds due to the fixed stack size + used by [`StoreOnHeap`], so you may want to try a Vec-based stack instead which + can grow as needed. + 2. You may want to avoid heap allocations entirely. You can use a fixed-size + stack with in-line arrays, which will place the entire storage in-line into + [`UnwindContext`]. " )] /// -/// If you need to avoid [`UnwindContext`] from allocating memory, e.g. for signal safety, -/// you can provide you own storage specification: +/// Here's an implementation which uses a fixed-size stack and allocates everything in-line, +/// which will cause `UnwindContext` to be large: +/// /// ```rust,no_run /// # use gimli::*; /// # @@ -1923,9 +1933,16 @@ impl UnwindContextStorage for StoreOnHeap { /// Common context needed when evaluating the call frame unwinding information. /// -/// This structure can be large so it is advisable to place it on the heap. +/// By default, this structure is small and allocates its internal storage +/// on the heap using [`Box`] during [`UnwindContext::new`]. +/// +/// This can be overridden by providing a custom [`UnwindContextStorage`] type parameter. +/// When using a custom storage with in-line arrays, the [`UnwindContext`] type itself +/// will be big, so in that case it's recommended to place [`UnwindContext`] on the +/// heap, e.g. using `Box::new(UnwindContext::::new_in())`. +/// /// To avoid re-allocating the context multiple times when evaluating multiple -/// CFI programs, it can be reused. +/// CFI programs, the same [`UnwindContext`] can be reused for multiple unwinds. /// /// ``` /// use gimli::{UnwindContext, UnwindTable}; @@ -1935,7 +1952,7 @@ impl UnwindContextStorage for StoreOnHeap { /// # let eh_frame: gimli::EhFrame<_> = unreachable!(); /// # let bases = unimplemented!(); /// // An uninitialized context. -/// let mut ctx = Box::new(UnwindContext::new()); +/// let mut ctx = UnwindContext::new(); /// /// // Initialize the context by evaluating the CIE's initial instruction program, /// // and generate the unwind table. From 364434ba30a62ec55dd6f31595eea1785538aa30 Mon Sep 17 00:00:00 2001 From: Markus Stange Date: Mon, 11 Mar 2024 18:37:17 -0400 Subject: [PATCH 2/2] Apply review suggestion (prefer Box over Vec) Co-authored-by: Philip Craig --- src/read/cfi.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/read/cfi.rs b/src/read/cfi.rs index 1320b5b3..37728ac3 100644 --- a/src/read/cfi.rs +++ b/src/read/cfi.rs @@ -1872,7 +1872,8 @@ on the heap using [`Box`]. This is the default storage type parameter for [`Unwi You may want to supply your own storage type for one of the following reasons: 1. In rare cases you may run into failed unwinds due to the fixed stack size - used by [`StoreOnHeap`], so you may want to try a Vec-based stack instead which + used by [`StoreOnHeap`], so you may want to try a larger `Box`. If denial + of service is not a concern, then you could also try a `Vec`-based stack which can grow as needed. 2. You may want to avoid heap allocations entirely. You can use a fixed-size stack with in-line arrays, which will place the entire storage in-line into