From 31ac13a5eaaf08b21d6c52776e1f4b3d91eb911a Mon Sep 17 00:00:00 2001 From: Mark Mansi Date: Fri, 25 Feb 2022 16:40:55 -0600 Subject: [PATCH 1/3] document ErrorGuaranteed --- src/SUMMARY.md | 1 + src/diagnostics/error-guaranteed.md | 36 +++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 src/diagnostics/error-guaranteed.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 3189b9364..e74ef5e4e 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -142,6 +142,7 @@ - [`LintStore`](./diagnostics/lintstore.md) - [Diagnostic Codes](./diagnostics/diagnostic-codes.md) - [Diagnostic Items](./diagnostics/diagnostic-items.md) + - [`ErrorGuaranteed`](./diagnostics/error-guaranteed.md) # MIR to Binaries diff --git a/src/diagnostics/error-guaranteed.md b/src/diagnostics/error-guaranteed.md new file mode 100644 index 000000000..ebed88e24 --- /dev/null +++ b/src/diagnostics/error-guaranteed.md @@ -0,0 +1,36 @@ +# `ErrorGuaranteed` + +The previous sections have been about the error message that a user of the +compiler sees. But emitting an error can also have a second important side +effect within the compiler source code: it generates an +[`ErrorGuaranteed`][errorguar]. + +`ErrorGuaranteed` is a zero-sized type that is unconstructable outside of the +[`rustc_errors`][rerrors] crate. It is generated whenever an error is reported +to the user, so that if your compiler code ever encounters a value of type +`ErrorGuaranteed`, the compilation is _statically guaranteed to fail_. This is +useful for avoiding unsoundness bugs because you can statically check that an +error code path leads to a failure. + +There are some important considerations about the usage of `ErrorGuaranteed`: + +* It does _not_ convey information about the _kind_ of error. For example, the + error may be due (indirectly) to an ICE. Thus, you should not rely on + `ErrorGuaranteed` in deciding whether to emit an error or what kind of error + to emit. + +* `ErrorGuaranteed` should not be used to indicated that a compilation _will + emit_ an error in the future. It should be used to indicate that an error + _has already been_ emitted -- that is, the [`emit()`][emit] function has + already been called. For example, if we detect that a future part of the + compiler will error, we _cannot_ use `ErrorGuaranteed` unless we first emit + an error ourselves. + +Thankfully, in most cases, it should be statically impossible to abuse +`ErrorGuaranteed`. + + +[errorguar]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.ErrorGuaranteed.html +[rerrors]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/index.html +[dsp]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.Handler.html#method.delay_span_bug +[emit]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/diagnostic_builder/struct.DiagnosticBuilder.html#method.emit From 1546808472447c8b7755ade533c31e25cff067bc Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Wed, 2 Mar 2022 09:36:20 -0600 Subject: [PATCH 2/3] Fix typos Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com> --- src/diagnostics/error-guaranteed.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/diagnostics/error-guaranteed.md b/src/diagnostics/error-guaranteed.md index ebed88e24..53a26c79b 100644 --- a/src/diagnostics/error-guaranteed.md +++ b/src/diagnostics/error-guaranteed.md @@ -16,10 +16,10 @@ There are some important considerations about the usage of `ErrorGuaranteed`: * It does _not_ convey information about the _kind_ of error. For example, the error may be due (indirectly) to an ICE. Thus, you should not rely on - `ErrorGuaranteed` in deciding whether to emit an error or what kind of error + `ErrorGuaranteed` when deciding whether to emit an error, or what kind of error to emit. -* `ErrorGuaranteed` should not be used to indicated that a compilation _will +* `ErrorGuaranteed` should not be used to indicate that a compilation _will emit_ an error in the future. It should be used to indicate that an error _has already been_ emitted -- that is, the [`emit()`][emit] function has already been called. For example, if we detect that a future part of the From 620e6b7aaa50836c66524c90bdb06a82d3a5d89c Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Fri, 22 Apr 2022 14:02:07 -0500 Subject: [PATCH 3/3] Clarify Niko comment Co-authored-by: Niko Matsakis --- src/diagnostics/error-guaranteed.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/diagnostics/error-guaranteed.md b/src/diagnostics/error-guaranteed.md index 53a26c79b..5a9b7f335 100644 --- a/src/diagnostics/error-guaranteed.md +++ b/src/diagnostics/error-guaranteed.md @@ -15,7 +15,8 @@ error code path leads to a failure. There are some important considerations about the usage of `ErrorGuaranteed`: * It does _not_ convey information about the _kind_ of error. For example, the - error may be due (indirectly) to an ICE. Thus, you should not rely on + error may be due (indirectly) to a `delay_span_bug` or other compiler error. + Thus, you should not rely on `ErrorGuaranteed` when deciding whether to emit an error, or what kind of error to emit.