From a36ce88d77950aba7c94314295bef73439ee84aa Mon Sep 17 00:00:00 2001 From: Akshay Narayan Date: Wed, 19 Apr 2023 17:37:43 -0700 Subject: [PATCH 1/2] Add documentation on wrap_err vs wrap_err_with --- src/lib.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index e7251c2..8de8128 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1093,6 +1093,13 @@ pub type Result = core::result::Result; /// # panic!("expected downcast to succeed"); /// } /// ``` +/// +/// # `wrap_err` vs `wrap_err_with` +/// +/// Depending on the instance of [`EyreHandler`] that is installed, using `wrap_err` can have +/// significant runtime cost (even if the error case does not happen), since [`EyreHandler`] can +/// incur significant costs (e.g., taking a lock) on error creation. Depending on the context, it +/// may be significantly more efficient to use `wrap_err_with`. pub trait WrapErr: context::private::Sealed { /// Wrap the error value with a new adhoc error #[cfg_attr(track_caller, track_caller)] From 4919e044e7ef8c30b036097256447bb7869e8d3b Mon Sep 17 00:00:00 2001 From: Akshay Narayan Date: Mon, 20 Nov 2023 16:55:49 -0800 Subject: [PATCH 2/2] make the text clearer --- src/lib.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 840d91b..0ab328a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1099,10 +1099,10 @@ pub type Result = core::result::Result; /// /// # `wrap_err` vs `wrap_err_with` /// -/// Depending on the instance of [`EyreHandler`] that is installed, using `wrap_err` can have -/// significant runtime cost (even if the error case does not happen), since [`EyreHandler`] can -/// incur significant costs (e.g., taking a lock) on error creation. Depending on the context, it -/// may be significantly more efficient to use `wrap_err_with`. +/// `wrap_err` incurs a runtime cost even in the non-error case because it requires eagerly +/// constructing the error object. `wrap_err_with` avoids this cost through lazy evaluation. This +/// cost is proportional to the cost of the currently installed [`EyreHandler`]'s creation step. +/// `wrap_err` is useful in cases where an constructed error object already exists. pub trait WrapErr: context::private::Sealed { /// Wrap the error value with a new adhoc error #[cfg_attr(track_caller, track_caller)]