You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Sep 12, 2024. It is now read-only.
* error book wip oliver
* Update CHARTER.md
Co-authored-by: Jane Lusby <[email protected]>
* remove ignored dir oliver
Co-authored-by: Jane Lusby <[email protected]>
Copy file name to clipboardExpand all lines: CHARTER.md
+70-39
Original file line number
Diff line number
Diff line change
@@ -5,40 +5,62 @@
5
5
6
6
### Agree on and define common error handling terminology
7
7
8
-
- Recoverable error: An error that can be reacted and recovered from when encountered e.g. a missing file.
9
-
- Unrecoverable error: An error that cannot reasonably be reacted to or recovered from and which indicates a bug e.g. indexing out of bounds.
10
-
- Error Type: A type that represents a recoverable error. Error types can optionally implement the `Error` trait so that it can be reported to the user or be converted into a trait object.
11
-
- Reporting Type: A type that can store all recoverable errors an application may need to propagate and print them as error reports.
12
-
- Reporting types can represent the recoverable errors either via concrete types, likely parameterized, or trait objects.
13
-
- Reporting types often bundle context with errors when they are constructed, e.g. `Backtrace`.
14
-
- Reporting types often provide helper functions for creating ad hoc errors whose only purpose is to be reported e.g. `anyhow::format_err!` or `eyre::WrapErr`.
8
+
- Recoverable error: An error that can be reacted and recovered from when
9
+
encountered e.g. a missing file.
10
+
- Unrecoverable error: An error that cannot reasonably be reacted to or
11
+
recovered from and which indicates a bug e.g. indexing out of bounds.
12
+
- Error Type: A type that represents a recoverable error. Error types can
13
+
optionally implement the `Error` trait so that it can be reported to the user
14
+
or be converted into a trait object.
15
+
- Reporting Type: A type that can store all recoverable errors an application
16
+
may need to propagate and print them as error reports.
17
+
- Reporting types can represent the recoverable errors either via concrete
18
+
types, likely parameterized, or trait objects.
19
+
- Reporting types often bundle context with errors when they are
20
+
constructed, e.g. `Backtrace`.
21
+
- Reporting types often provide helper functions for creating ad hoc errors
22
+
whose only purpose is to be reported e.g. `anyhow::format_err!` or
23
+
`eyre::WrapErr`.
15
24
16
25
### Come to a consensus on current best practices
17
26
18
27
Here is a tentative starting point, subject to change:
19
28
20
29
- Use `Result` and `Error` types for recoverable errors.
21
30
- Use `panic` for unrecoverable errors.
22
-
- Implement `Error` for error types that may need to be reported to a human or be composed with other errors.
23
-
- Use enums for types representing multiple failure cases that may need to be handled.
24
-
- For libraries, oftentimes you want to support both reporting and handling so you implement `Error` on a possibly non-exhaustive enum.
25
-
- Error kind pattern for associating context with every enum variant without including the member in every enum variant.
26
-
- Convert to a reporting type when the error is no longer expected to be handled beyond reporting e.g. `anyhow::Error` or `eyre::Report` or when trait object + downcast error handling is preferable.
27
-
- Recommend `Box`ing concrete error types when stack size is an issue rather than `Box`ing and converting to `dyn Error`s.
28
-
- What is the consensus on handling `dyn Error`s? Should it be encouraged or discouraged? Should we look into making `Box<dyn Error...>` implement `Error`?
31
+
- Implement `Error` for error types that may need to be reported to a human or
32
+
be composed with other errors.
33
+
- Use enums for types representing multiple failure cases that may need to be
34
+
handled.
35
+
- For libraries, oftentimes you want to support both reporting and handling
36
+
so you implement `Error` on a possibly non-exhaustive enum.
37
+
- Error kind pattern for associating context with every enum variant without
38
+
including the member in every enum variant.
39
+
- Convert to a reporting type when the error is no longer expected to be handled
40
+
beyond reporting e.g. `anyhow::Error` or `eyre::Report` or when trait object +
41
+
downcast error handling is preferable.
42
+
- Recommend `Box`ing concrete error types when stack size is an issue rather
43
+
than `Box`ing and converting to `dyn Error`s.
44
+
- What is the consensus on handling `dyn Error`s? Should it be encouraged or
45
+
discouraged? Should we look into making `Box<dyn Error...>` implement `Error`?
29
46
30
47
31
48
### Identify pain points in error handling today
32
49
33
-
- Backtrace capture is expensive, but without it can be difficult to pinpoint the origin of errors
34
-
- unwrapping errors without first converting to a reporting type will often discard relevant information
35
-
- errors printed from `main` have to assume a prefixed `Error: `, sub-par control of output format when printing during termination.
36
-
- The `Error` trait only exposes three forms of context, can only represent singly-linked lists for chains of errors
50
+
- Backtrace capture is expensive, but without it can be difficult to pinpoint
51
+
the origin of errors
52
+
- unwrapping errors without first converting to a reporting type will often
53
+
discard relevant information
54
+
- errors printed from `main` have to assume a prefixed `Error: `, sub-par
55
+
control of output format when printing during termination.
56
+
- The `Error` trait only exposes three forms of context, can only represent
57
+
singly-linked lists for chains of errors
37
58
38
59
### Communicate current best practices
39
60
40
61
- Document the consensus.
41
-
- Communicate plan for future changes to error handling, and the libraries that future changes are being based off of.
62
+
- Communicate plan for future changes to error handling, and the libraries that
63
+
future changes are being based off of.
42
64
- Produce learning resources related to current best practices.
43
65
- New chapters in the book?
44
66
@@ -50,18 +72,23 @@ Here is a tentative starting point, subject to change:
50
72
- Evaluate value of features including:
51
73
- Single word width on stack
52
74
- Error wrapping with display types and with special downcast support.
53
-
- Report hook and configurable `dyn ReportHandler` type for custom report formats and content, similar to panic handler but for errors.
75
+
- Report hook and configurable `dyn ReportHandler` type for custom report
76
+
formats and content, similar to panic handler but for errors.
54
77
-`#[no_std]` support
55
78
56
79
### Consolidate ecosystem by merging best practice crates into std
57
80
58
81
- Provide a derive macro for `Error` in std.
59
-
- Stabilize the `Backtrace` type but possibly not `fn backtrace` on the `Error` trait.
60
-
- Provide necessary API on `Backtrace` to support crates like `color-backtrace`.
82
+
- Stabilize the `Backtrace` type but possibly not `fn backtrace` on the `Error`
83
+
trait.
84
+
- Provide necessary API on `Backtrace` to support crates like
85
+
`color-backtrace`.
61
86
- Move `Error` to core.
62
87
- Depends on generic member access.
63
-
- Requires resolving downcast dependency on `Box` and blocking the stabilization of `fn backtrace`.
64
-
- Potentially stabilize an error reporting type based on `anyhow` and `eyre` now that they're close to having identical feature sets.
88
+
- Requires resolving downcast dependency on `Box` and blocking the
89
+
stabilization of `fn backtrace`.
90
+
- Potentially stabilize an error reporting type based on `anyhow` and `eyre` now
91
+
that they're close to having identical feature sets.
65
92
66
93
### Add missing features
67
94
@@ -72,11 +99,13 @@ Here is a tentative starting point, subject to change:
72
99
73
100
## Non Goals
74
101
75
-
- This group should not be involved in managing design discussions for the `Try` trait, `try` blocks, or `try` fns.
102
+
- This group should not be involved in managing design discussions for the `Try`
103
+
trait, `try` blocks, or `try` fns.
76
104
77
105
## Membership Requirements
78
106
79
-
- Group membership is open, any interested party can participate in discussions, repeat contributors will be added to appropriate teams.
107
+
- Group membership is open, any interested party can participate in discussions,
108
+
repeat contributors will be added to appropriate teams.
80
109
81
110
## Additional Questions
82
111
@@ -86,20 +115,20 @@ I'm not sure, my main concern is getting prompt feedback on RFCs.
86
115
87
116
### Why should this be a project group over a community effort?
88
117
89
-
There isn't anything in this project group that can't be handled as a
90
-
community effort, but centralizing work into a project group should help
91
-
speed things. Error handling is a core aspect of the language and changes in
92
-
error handling have large impacts on the ecosystem. Ensuring that efforts to
93
-
refine error handling within Rust have sufficient resources and don't stall
94
-
out is in the best interests of the community. By organizing efforts as a
95
-
project group we will hopefully have an easier time recruiting new members,
96
-
getting attention on RFCs from members of the libs team, and using the
97
-
established resources and expertise of the rust organization for coordinating
98
-
our efforts.
118
+
There isn't anything in this project group that can't be handled as a community
119
+
effort, but centralizing work into a project group should help speed things.
120
+
Error handling is a core aspect of the language and changes in error handling
121
+
have large impacts on the ecosystem. Ensuring that efforts to refine error
122
+
handling within Rust have sufficient resources and don't stall out is in the
123
+
best interests of the community. By organizing efforts as a project group we
124
+
will hopefully have an easier time recruiting new members, getting attention on
125
+
RFCs from members of the libs team, and using the established resources and
126
+
expertise of the rust organization for coordinating our efforts.
99
127
100
128
### What do you expect the relationship to the team be?
101
129
102
-
The project group will create RFCs for various changes to the standard library and the team will review them via the standard RFC process.
130
+
The project group will create RFCs for various changes to the standard library
131
+
and the team will review them via the standard RFC process.
103
132
104
133
### Who are the initial shepherds/leaders? (This is preferably 2–3 individuals, but not required.)
105
134
@@ -111,11 +140,13 @@ Temporary.
111
140
112
141
### If it is temporary, how long do you see it running for?
113
142
114
-
This depends pretty heavily on how quickly the RFCs move, anywhere between 6 months and 2 years I'd guess but don't quote me on this.
143
+
This depends pretty heavily on how quickly the RFCs move, anywhere between 6
144
+
months and 2 years I'd guess but don't quote me on this.
115
145
116
146
### If applicable, which other groups or teams do you expect to have close contact with?
117
147
118
-
Primarily the libs team, but there may be some small interactions with the lang team, compiler team, and traits working group.
148
+
Primarily the libs team, but there may be some small interactions with the lang
Copy file name to clipboardExpand all lines: meetings/2020-09-28.md
+25-14
Original file line number
Diff line number
Diff line change
@@ -4,11 +4,14 @@
4
4
5
5
## Agenda Items
6
6
7
-
- Prototyping an implementation of `std::core::Error` and stabilizing `#[feature(backtrace)]`
7
+
- Prototyping an implementation of `std::core::Error` and stabilizing
8
+
`#[feature(backtrace)]`
8
9
- Identifying existing issues and RFCs that we should track
9
10
-https://github.com/rust-lang/rfcs/pull/2895
10
11
- Planning for "Communicating best practices"
11
-
- "How users expect error handling to be, As in, we take a leap into the future and assume all this was implemented into the language, then how it would potentially look"
12
+
- "How users expect error handling to be, As in, we take a leap into the future
13
+
and assume all this was implemented into the language, then how it would
14
+
potentially look"
12
15
13
16
14
17
# Meeting Minutes
@@ -31,21 +34,26 @@ People in attendance:
31
34
- Jubilee Young
32
35
33
36
## Topic 1: Discussing stabilizing `Backtrace`
34
-
- Global hooks vs Boxing vs a trait-based approach for stabilizing `Backtrace` in `core`.
37
+
- Global hooks vs Boxing vs a trait-based approach for stabilizing `Backtrace`
38
+
in `core`.
35
39
- Going with the trait-based impl for `Backtrace` in core.
36
-
- Private trait + public newtype wrapper.
37
-
- Start with `eddyb`'s impl and see how many hooks are necessary along the way.
40
+
- Private trait + public newtype wrapper.
41
+
- Start with `eddyb`'s impl and see how many hooks are necessary along the
42
+
way.
38
43
- private trait with a public newtype wrapper
39
44
- newtype wrapper is an interface not subject to coherence so we can add new
40
-
methods without worrying about breaking changes downstream
45
+
methods without worrying about breaking changes downstream
- trait-based approaches have fewer magic compiler pieces and so would be easier
48
+
to put together
49
+
- `write_backtrace_to(&mut dyn FormatterThing) ->
50
+
Result<(),FormatterThing::Error>`
44
51
- ultimately about moving `Error` to core
45
-
- should we do a trait object based solution internally with an unstable `Backtrace`
46
-
trait in core and a stable `Backtrace` type in core or should it use global hooks
47
-
like `panic_impl`
48
-
-**need a prototype solution for exposing `Backtrace` as a type in `core` with the interface it currently provides in `std`**
52
+
- should we do a trait object based solution internally with an unstable
53
+
`Backtrace` trait in core and a stable `Backtrace` type in core or should it
54
+
use global hooks like `panic_impl`
55
+
-**need a prototype solution for exposing `Backtrace` as a type in `core` with
56
+
the interface it currently provides in `std`**
49
57
50
58
## Topic 2: What RFCs should this group be tracking?
51
59
- This group will have its own Project board to track relevant issues/RFCs.
@@ -61,15 +69,18 @@ People in attendance:
61
69
- Facilitate communication of best practices via a Book/documentation.
62
70
- Should include some guidance on FFI error handling.
63
71
- Adding a book section to the project repo (using mdbook).
64
-
- Publish *The Rust Error Book* (name subject to change) and potentially contribute to *The Book* to make its error handling recommendations consistent with what this group decides.
72
+
- Publish *The Rust Error Book* (name subject to change) and potentially
73
+
contribute to *The Book* to make its error handling recommendations consistent
74
+
with what this group decides.
65
75
66
76
## Topic 4: What is the long-term vision of what error handling in Rust looks like?
67
77
-`Error` in `core`.
68
78
- Stabilization of unstable `Error` interfaces.
69
79
- Iterator API on `Backtrace`.
70
80
- Generic member access (possibly with two-way flow).
71
81
- Error return traces.
72
-
- Some way to universally hook into all error reporting points for consistent error reporting.
82
+
- Some way to universally hook into all error reporting points for consistent
0 commit comments