document #[panic_handler] #362

japaric · 2018-06-20T19:18:58Z

Havvy · 2018-06-20T23:00:26Z

src/beneath-std.md

+that `#![no_std]` developers have to deal with (i.e. provide) to build `#![no_std]` binary crates. A
+(likely incomplete) list of such features is shown below:
+
+- #[lang = "eh_personality"]


We explicitly do not document lang items and anything unstable. Listing them goes against that.

Havvy · 2018-06-20T23:00:34Z

src/panic-implementation.md

@@ -0,0 +1,35 @@
+## #[panic_implementation]
+
+The `#[panic_implementation]` attribute can only be applied to a function with signature


The attribute name is written without the #[] surrounding it.

Havvy · 2018-06-20T23:01:09Z

src/panic-implementation.md

+The `#[panic_implementation]` attribute can only be applied to a function with signature
+`fn(&PanicInfo) -> !`. The function marked with this attribute defines the behavior of `panic!` in
+`#![no_std]` applications. There must be a *single* `#[panic_implementation]` function in the
+dependency graph of a binary / dylib / cdylib crate.


Use commas, not /s.

Havvy · 2018-06-20T23:02:39Z

src/panic-implementation.md

+`#![no_std]` applications. There must be a *single* `#[panic_implementation]` function in the
+dependency graph of a binary / dylib / cdylib crate.
+
+The `PanicInfo` struct contains information about the location of the panic. The API of `PanicInfo`


Put the link around the first PanicInfo. E.g. [`PanicInfo`].

Havvy · 2018-06-20T23:03:29Z

src/panic-implementation.md

+dependency graph of a binary / dylib / cdylib crate.
+
+The `PanicInfo` struct contains information about the location of the panic. The API of `PanicInfo`
+can be found in the [API docs]. As of 1.28-beta (2018-06-21) there's a difference between


We don't discuss anything that's not stable. This includes beta versions. Nor do we discuss older versions.

japaric · 2018-06-22T02:58:18Z

@Havvy Thanks for the review. I think I have addressed all your comments in the last commit. Let me know if I missed something.

Havvy

Looking better.

One nit. One not so nit.

And one thing that doesn't really have a line number. The attributes.md page needs to list panic_implementation.

--

Also, while it's not stable right now, the documentation cannot use feature flags. They'll have to be removed before the PR can be merged.

Havvy · 2018-06-22T03:08:44Z

src/beneath-std.md

+# Beneath `std`
+
+This section documents features that are provided by the standard library and that `#![no_std]`
+developers have to deal with (i.e. provide) to build `#![no_std]` binary crates. A list of such


"deal with (i.e. provide)" should just be "provide".

Havvy · 2018-06-22T03:15:14Z

src/SUMMARY.md

@@ -87,6 +87,8 @@
    - [Behavior considered undefined](behavior-considered-undefined.md)
    - [Behavior not considered unsafe](behavior-not-considered-unsafe.md)

+- [Beneath `std`](beneath-std.md)


I don't like this name. At all. It implies this is information only useful for std, since it's stuff beneath it. And it also implies the things that std can do that other crates cannot. Perhaps something like "Runtime", since the things you have to implement are all going to be what's effectively the Rust Runtime. Then we would also be able to document what the standard behaviour does.

japaric · 2018-09-07T10:38:39Z

Hey, @Havvy. Sorry for the radio silence. panic_handler (previously panic_implementation) is in FCP now so I have picked up the work here.

I have addressed your comment about renaming the section to "the Rust runtime" and have documented the standard behavior.

japaric · 2018-09-07T10:39:19Z

src/runtime.md

+### Standard behavior
+
+The standard library provides an implementation of `panic_handler` than can be
+statically customized using the `-C panic` flag. `-C panic=abort` makes panics


I'm wasn't 100% sure if we can refer to rustc flags in the reference.

generally not; they'd go in the rustc book (which this already is there)

Ok, I have simplified this to point to the book.

japaric · 2018-09-07T10:40:22Z

src/runtime.md

+statically customized using the `-C panic` flag. `-C panic=abort` makes panics
+abort the process, and `-C panic=unwind` makes panics unwind the panicking
+thread. If no panicking behavior is specified using `-C panic` one of these two
+behaviors is chosen according to the compilation target.


I could expand here and mention that the default behavior is in the specification of the compilation target but target specifications are unstable. (See rustc -Z unstable-options --print target-spec-json).

A table that contains the information would perhaps be useful. Probably don't want to do that in this PR though, since this one is shaping up to be mergable.

japaric · 2018-09-07T10:42:18Z

src/runtime.md

+### Standard behavior
+
+The standard library provides an implementation of `panic_handler` than can be
+statically customized using the `-C panic` flag. `-C panic=abort` makes panics


The standard library also lets you customize the panicking behavior at runtime via the panic::set_hook but I wasn't sure if we should document standard API here.

generally not :)

The fact that panic behavior can be changed is a language level detail and should be documented. Linking to the function that shows how to change it would be useful.

Mark-Simulacrum

This looks good to me. Approval from people more familiar with the reference would be good though.

@whitequark

…imulacrum stabilize #[panic_handler] closes rust-lang#44489 ### Update(2018-09-07) This was proposed for stabilization in rust-lang#44489 (comment) and its FCP with disposition to merge / accept is nearly over. The summary of what's being stabilized can be found in rust-lang#44489 (comment) Documentation PRs: - Reference. rust-lang/reference#362 - Nomicon. rust-lang/nomicon#75 --- `#[panic_implementation]` was implemented recently in rust-lang#50338. `#[panic_implementation]` is basically the old `panic_fmt` language item but in a less error prone (\*) shape. There are still some issues and questions to sort out around this feature (cf. rust-lang#44489) but this PR is meant to start a discussion about those issues / questions with the language team. (\*) `panic_fmt` was not type checked; changes in its function signature caused serious, silent binary size regressions like the one observed in rust-lang#43054 Some unresolved questions from rust-lang#44489: > Should the Display of PanicInfo format the panic information as "panicked at 'reason', > src/main.rs:27:4", as "'reason', src/main.rs:27:4", or simply as "reason". The current implementation formats `PanicInfo` as the first alternative, which is how panic messages are formatted by the `std` panic handler. The `Display` implementation is more than a convenience: `PanicInfo.message` is unstable so it's not possible to replicate the `Display` implementation on stable. > Is this design compatible, or can it be extended to work, with unwinding implementations for > no-std environments? I believe @whitequark made more progress with unwinding in no-std since their last comment in rust-lang#44489. Perhaps they can give us an update? --- Another unresolved question is where this feature should be documented. The feature currently doesn't have any documentation. cc @rust-lang/lang cc @jackpot51 @alevy @phil-opp

@whitequark

…imulacrum stabilize #[panic_handler] closes rust-lang#44489 ### Update(2018-09-07) This was proposed for stabilization in rust-lang#44489 (comment) and its FCP with disposition to merge / accept is nearly over. The summary of what's being stabilized can be found in rust-lang#44489 (comment) Documentation PRs: - Reference. rust-lang/reference#362 - Nomicon. rust-lang/nomicon#75 --- `#[panic_implementation]` was implemented recently in rust-lang#50338. `#[panic_implementation]` is basically the old `panic_fmt` language item but in a less error prone (\*) shape. There are still some issues and questions to sort out around this feature (cf. rust-lang#44489) but this PR is meant to start a discussion about those issues / questions with the language team. (\*) `panic_fmt` was not type checked; changes in its function signature caused serious, silent binary size regressions like the one observed in rust-lang#43054 Some unresolved questions from rust-lang#44489: > Should the Display of PanicInfo format the panic information as "panicked at 'reason', > src/main.rs:27:4", as "'reason', src/main.rs:27:4", or simply as "reason". The current implementation formats `PanicInfo` as the first alternative, which is how panic messages are formatted by the `std` panic handler. The `Display` implementation is more than a convenience: `PanicInfo.message` is unstable so it's not possible to replicate the `Display` implementation on stable. > Is this design compatible, or can it be extended to work, with unwinding implementations for > no-std environments? I believe @whitequark made more progress with unwinding in no-std since their last comment in rust-lang#44489. Perhaps they can give us an update? --- Another unresolved question is where this feature should be documented. The feature currently doesn't have any documentation. cc @rust-lang/lang cc @jackpot51 @alevy @phil-opp

@whitequark

stabilize #[panic_handler] closes #44489 ### Update(2018-09-07) This was proposed for stabilization in #44489 (comment) and its FCP with disposition to merge / accept is nearly over. The summary of what's being stabilized can be found in #44489 (comment) Documentation PRs: - Reference. rust-lang/reference#362 - Nomicon. rust-lang/nomicon#75 --- `#[panic_implementation]` was implemented recently in #50338. `#[panic_implementation]` is basically the old `panic_fmt` language item but in a less error prone (\*) shape. There are still some issues and questions to sort out around this feature (cf. #44489) but this PR is meant to start a discussion about those issues / questions with the language team. (\*) `panic_fmt` was not type checked; changes in its function signature caused serious, silent binary size regressions like the one observed in #43054 Some unresolved questions from #44489: > Should the Display of PanicInfo format the panic information as "panicked at 'reason', > src/main.rs:27:4", as "'reason', src/main.rs:27:4", or simply as "reason". The current implementation formats `PanicInfo` as the first alternative, which is how panic messages are formatted by the `std` panic handler. The `Display` implementation is more than a convenience: `PanicInfo.message` is unstable so it's not possible to replicate the `Display` implementation on stable. > Is this design compatible, or can it be extended to work, with unwinding implementations for > no-std environments? I believe @whitequark made more progress with unwinding in no-std since their last comment in #44489. Perhaps they can give us an update? --- Another unresolved question is where this feature should be documented. The feature currently doesn't have any documentation. cc @rust-lang/lang cc @jackpot51 @alevy @phil-opp

Centril · 2019-01-10T18:55:42Z

Ping from triage, @japaric what's the status of this PR?

ehuss · 2019-03-11T02:35:42Z

I have rebased this PR and updated for the review comments.

I noticed nothing really describes "panics" or panic behavior in the reference, seems like something that would be good for the future.

I was thinking maybe in a future PR that global_allocator could be moved to the runtime page. However, I'm not really confident that the allocator is part of the "runtime". What do people consider is part of the Rust "runtime"? Where is the line drawn?

Done

Centril · 2019-03-11T02:42:08Z

@ehuss This is a good start; merge when you feel like it :)

- Address review comments. - Some minor formatting adjustments.

Update books Update reference, book, rust-by-example, edition-guide, embedded-book ## reference 15 commits in 41493ff..27ad493 2019-03-05 12:32:22 +0100 to 2019-03-26 02:06:15 +0100 - Document wasm_import_module for #[link]. (rust-lang/reference#554) - Fix tidy error. (rust-lang/reference#552) - Some minor contributing updates. (rust-lang/reference#551) - Document `type_length_limit`. (rust-lang/reference#546) - Add some terms to the glossary. (rust-lang/reference#547) - Document `target_feature` and `cfg_target_feature`. (rust-lang/reference#545) - Remove undocumented page (rust-lang/reference#539) - Reorg and update attributes (rust-lang/reference#537) - Fix some minor link errors. (rust-lang/reference#538) - Add linkchecker. (rust-lang/reference#521) - Expand docs on Macros By Example. (rust-lang/reference#511) - document #[panic_handler] (rust-lang/reference#362) - document #[used] (rust-lang/reference#361) - Note that UB is program-global (rust-lang/reference#490) - Fix copy-paste error in procedural-macros.md (rust-lang/reference#533) ## book 16 commits in 9cffbeabec3bcec42d09432bfe7705125c848889..b93ec30bbc7b1b5c2f44223249ab359bed2ed5a6 2019-03-02 08:22:41 -0500 to 2019-03-26 16:54:10 -0400 - Unignore example that now compiles - Fix code snippet (rust-lang/book#1863) - Fix mdbook link text in readme (rust-lang/book#1881) - Wrap to 80 cols - Make sentence more complete (rust-lang/book#1885) - consistenly use increment and decrement (rust-lang/book#1884) - Fix link to Reference's conditional-compilation. (rust-lang/book#1878) - Fix subject/verb agreement - Remove nostarch snapshot files that have been incorporated and checked - haha teach the dictionary steve's name - Add authorship info to the front page - fix accidental <ol>'s (rust-lang/book#1866) - Edits to Macros (rust-lang/book#1848) - Mention `lock` returns `MutexGuard` wrapped in a `LockResult` - Add an example that illustrates NLL (rust-lang/book#1842) - change the parameter name from `type` to `kind` (rust-lang/book#1845) ## rust-by-example 33 commits in 2ce92beabb912d417a7314d6da83ac9b50dc2afb..f68ef3d0f4959f6a7d92a08d9994b117f0f4d32d 2018-11-20 10:10:23 -0500 to 2019-03-12 15:32:12 -0300 - Fix some broken links. (rust-lang/rust-by-example#1161) - Update links in README (rust-lang/rust-by-example#1167) - Add score/lifetimes/trait.md (rust-lang/rust-by-example#1168) - Fix rust-lang/rust-by-example#1147 - No more `open_mode` method (rust-lang/rust-by-example#1164) - Fix for loop description in list print example (rust-lang/rust-by-example#1162) - Add link to Cargo chapter in the index page (rust-lang/rust-by-example#1159) - Fix grammar in sentence about integer notation (rust-lang/rust-by-example#1157) - Do not use deprecated functions from `std::error::Error` trait (rust-lang/rust-by-example#1151) - Update new_types.md to clarify conversion to base type (rust-lang/rust-by-example#1148) - Fix compatibility with Rust 2018 (rust-lang/rust-by-example#1150) - Hello: Fix hint link in `fmt` chapter. (rust-lang/rust-by-example#1146) - Clarify pub(restricted) example a bit (rust-lang/rust-by-example#1133) - Add "literal" to list of macro designators (rust-lang/rust-by-example#1153) - Minor fixes for the macros chapter (rust-lang/rust-by-example#1113) - Use new book links instead of the old second-edition ones (rust-lang/rust-by-example#1143) - Recommend implementing Display over ToString (rust-lang/rust-by-example#1145) - Remove unused import and format with `rustfmt` (rust-lang/rust-by-example#1144) - fix typo (rust-lang/rust-by-example#1142) - Update syntax for 2018 Edition (rust-lang/rust-by-example#1136) - Added two missing full stops (rust-lang/rust-by-example#1138) - Removed unnecessary spaces before macro designators in macros/dry (rust-lang/rust-by-example#1139) - fix install mdbook command (rust-lang/rust-by-example#1128) - Changed word `function` to `type` in comment of fn area (rust-lang/rust-by-example#1132) - Added two missing backticks in generics/multi_bounds (rust-lang/rust-by-example#1129) - Fixed small logic error in error/option_unwrap/and_then (rust-lang/rust-by-example#1127) - Fix typo (rust-lang/rust-by-example#1125) - The code of conduct link was dead. I fixed it. (rust-lang/rust-by-example#1122) - I added a space in the Display fmt for Complex (rust-lang/rust-by-example#1123) - Fix Rust install link in the index (rust-lang/rust-by-example#1124) - Update cargo conventions section (rust-lang/rust-by-example#1121) - Fixed curly braces in the `To and from Strings` chapter to be parentheses (rust-lang/rust-by-example#1120) - Edit a typo (rust-lang/rust-by-example#1119) - Fixes rust-lang/rust-by-example#1115 by correcting the typo from into_iterator to into_iter (rust-lang/rust-by-example#1118) ## edition-guide 1 commits in aa0022c875907886cae8f3ef8e9ebf6e2a5e728d..b56ddb11548450a6df4edd1ed571b2bc304eb9e6 2019-02-27 22:10:39 -0800 to 2019-03-10 10:23:16 +0100 - Links fixes (rust-lang/edition-guide#133) ## embedded-book 6 commits in 9e656ead82bfe869493dec82653a52e27fa6a05c..07fd3880ea0874d82b1d9ed30ad3427ec98b4e8a 2019-03-03 16:03:26 +0000 to 2019-03-27 15:40:52 +0000 - Fix test errors. (rust-embedded/book#180) - Update qemu.md (rust-embedded/book#170) - Update no-std.md to remove obsolete FAQ link (rust-embedded/book#177) - We've come a long way :) (rust-embedded/book#176) - Correct link to team (rust-embedded/book#175) - Update some book links to their new homes. (rust-embedded/book#173)

japaric mentioned this pull request Jun 20, 2018

stabilize #[panic_handler] rust-lang/rust#51366

Merged

Havvy reviewed Jun 20, 2018

View reviewed changes

Havvy previously requested changes Jun 22, 2018

View reviewed changes

Havvy added the RFC Stabilization Docs Documentation required for stabilizing a feature label Jun 22, 2018

japaric mentioned this pull request Sep 7, 2018

Tracking issue for RFC 2070: stable mechanism to specify the behavior of panic! in no-std applications rust-lang/rust#44489

Closed

7 tasks

japaric commented Sep 7, 2018

View reviewed changes

japaric changed the title ~~document #[panic_implementation]~~ document #[panic_handler] Sep 7, 2018

Mark-Simulacrum approved these changes Sep 7, 2018

View reviewed changes

QuietMisdreavus mentioned this pull request Oct 29, 2018

Improve size-optimizing FAQ docs rust-lang/prev.rust-lang.org#1212

Closed

ehuss mentioned this pull request Mar 8, 2019

Undocumented Attributes #532

Closed

6 tasks

ehuss force-pushed the panic branch from ade532c to f659a93 Compare March 11, 2019 02:32

Centril approved these changes Mar 11, 2019

View reviewed changes

japaric added 2 commits March 11, 2019 14:32

document #[panic_implementation]

1242944

address review comments

dba3cbb

japaric and others added 4 commits March 11, 2019 14:32

panic_implementation -> panic_handler; beneath std -> the Rust runtime

ddac383

ignore test

24f3bd8

link to the book

1985db0

Update panic_handler.

d17ef56

- Address review comments. - Some minor formatting adjustments.

ehuss force-pushed the panic branch from f659a93 to d17ef56 Compare March 11, 2019 21:35

ehuss merged commit e244040 into rust-lang:master Mar 11, 2019

ehuss mentioned this pull request Mar 22, 2019

Update books rust-lang/rust#59366

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

document #[panic_handler] #362

document #[panic_handler] #362

japaric commented Jun 20, 2018

Havvy Jun 20, 2018

Havvy Jun 20, 2018

Havvy Jun 20, 2018

Havvy Jun 20, 2018

Havvy Jun 20, 2018

japaric commented Jun 22, 2018

Havvy left a comment

Havvy Jun 22, 2018

Havvy Jun 22, 2018

japaric commented Sep 7, 2018

japaric Sep 7, 2018

steveklabnik Sep 7, 2018

japaric Sep 7, 2018

japaric Sep 7, 2018

Havvy Sep 7, 2018

japaric Sep 7, 2018

steveklabnik Sep 7, 2018

Havvy Sep 7, 2018

Mark-Simulacrum left a comment

Centril commented Jan 10, 2019

ehuss commented Mar 11, 2019

Centril commented Mar 11, 2019

		@@ -0,0 +1,35 @@
		## #[panic_implementation]

		The `#[panic_implementation]` attribute can only be applied to a function with signature

document #[panic_handler] #362

document #[panic_handler] #362

Conversation

japaric commented Jun 20, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

japaric commented Jun 22, 2018

Havvy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

japaric commented Sep 7, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Mark-Simulacrum left a comment

Choose a reason for hiding this comment

Centril commented Jan 10, 2019

ehuss commented Mar 11, 2019

Centril commented Mar 11, 2019