Add statements on intrinsics. #148

vjonaswolf · 2025-01-17T08:35:40Z

No description provided.

vjonaswolf · 2025-01-17T08:36:05Z

@vapdrs would you like to have a look at my minimal first version?

PLeVasseur · 2025-01-17T21:00:58Z

Hey @vjonaswolf -- thanks for kicking things off :)

Could you add in a small description to the PR summary, so we can have a bit of traceability later?

vapdrs

Thank you for putting this together. Overall I'd say this covers the necessary basics for this topic. Some "nice to have" additions would a code example or link to one for transmute, and a statement on the considerations that should be taken for safety when using intrinics. If you would like me to draft some wording for those, let me know.

.../initiatives/safe-use-of-unsafe-guidelines/learn_unsafe_rust/src/core_unsafety/intrinsics.md

vapdrs · 2025-01-21T15:46:51Z

.../initiatives/safe-use-of-unsafe-guidelines/learn_unsafe_rust/src/core_unsafety/intrinsics.md

+
+Thus, the clear recommendation is not using the experimental compiler intrinsics in a safety-critical project.
+
+With `transmute` there is one major exception. However, `transmute` is handled in other parts of the guidelines.


I'm not sure what the exception being referred to here is,

transmute is exceptional because it isn't Experimental

This is different from most other intrinsics, but copy, copy_nonoverlapping, and write_bytes are also not marked as Experimental

transmute is exceptional because it doesn't mention a stabilized API in its documentation

There is std::mem::transmute, however I guess this is just a re-export of the instrinsic not an API

copy, copy_nonoverlapping, and write_bytes don't also reference a stabilized API, and have a std::ptr re-export

transmute is exceptional because it is an experimental compiler intrinsic that should not be avoided in a safety-critical project

It isn't experimental, so the above guidance doesn't really apply

The Rustonomicon also lists uses for copy and copy_nonoverlapping's re-exports when assigning to a memory location without invoking a drop

ping @vjonaswolf for his feedback on @vapdrs's comment

…guidelines/learn_unsafe_rust/src/core_unsafety/intrinsics.md Co-authored-by: Douglas Deslauriers <[email protected]>

…lf/safety-critical-rust-consortium into guideline-on-intrinsics

vapdrs

Looks good to me

vjonaswolf · 2025-02-12T14:43:59Z

closes #174

PLeVasseur

Hey @vjonaswolf -- thanks for taking this on! I've left a few notes poking around how much scope we see being in this chapter.

PLeVasseur · 2025-02-13T18:45:15Z

.../initiatives/safe-use-of-unsafe-guidelines/learn_unsafe_rust/src/core_unsafety/intrinsics.md

+
+Most of them are marked as experimental, unstable and useable in nightly versions of the compiler.
+
+Many intrinsics are accessible though a stabilized API located elsewhere in the Standard or Core Library. The documentation for each intrinsic typically references the stabilized API.


It may be useful to break this out into its own section and highlight some examples. What do you think?

Yes, there should be plenty of examples

Really, I'd say there should be an ontology of intrinsics here: a categorization of the stdlib intrinsics into different types.

PLeVasseur · 2025-02-13T18:46:17Z

.../initiatives/safe-use-of-unsafe-guidelines/learn_unsafe_rust/src/core_unsafety/intrinsics.md

+
+Many intrinsics are accessible though a stabilized API located elsewhere in the Standard or Core Library. The documentation for each intrinsic typically references the stabilized API.
+
+Thus, the clear recommendation is not using the experimental compiler intrinsics in a safety-critical project.


I can understand this general recommendation! Perhaps those exposed via other core or std APIs would be useful to discuss and note where undefined behavior can crop up?

I don't think this is the right way to approach this. As mentioned before, these chapters must:

Talk about how the safety works for this feature

Talk about things to think about when using them

Talk about when one might need to reach for them

Talk about best practices when you are reaching for them (this is where you say "try using the stabilized APIs instead" for some of these APIs)

This is unsafe code: people are already in a weird situation. They may have a good reason for reaching for an intrinsic, perhaps it's new and unstabilized, perhaps it's one of the more niche ones that never got a stable API, perhaps it's one of the atomic ones which have higher level stable APIs but not the lower level direct atomic accesses.

It should not be our job to say "don't do this", it should be our job to say "if you need to do this, here's how you make sure you actually need to do this, and here's how to make sure you're doing it right".

This is unsafe code: people are already in a weird situation.

I think this is fair.

@vjonaswolf -- perhaps we should take the safety-critical lens off here for the moment and broaden to helping people in a weird situation.

As we talked about a bit with @adfernandes, some of the work he's doing on the safety-critical pamphlet can help with noting in resources we reference like Learn unsafe Rust the context and certain things / sections to avoid or suggest alternatives to like "hey try to use these stabilized APIs instead, if possible".

PLeVasseur · 2025-02-13T18:49:38Z

.../initiatives/safe-use-of-unsafe-guidelines/learn_unsafe_rust/src/core_unsafety/intrinsics.md

+
+There are only few functions that are not marked as experimental: `copy`, `copy_nonoverlapping`, `write_bytes`, `transmute`.
+`transmute` is probably the most well-known and widely used of these APIs.
+`transmute` is handled in other parts of the guidelines.


Do you refer to the chapter on Invalid Values, particularly this section?

If so, it might be nice to make the link over there explicit.

Yes, please cross link.

PLeVasseur · 2025-02-13T18:53:53Z

.../initiatives/safe-use-of-unsafe-guidelines/learn_unsafe_rust/src/core_unsafety/intrinsics.md

+
+Rust provides a set of compiler intrinsics as part of `core` and `std` respectively (https://doc.rust-lang.org/std/intrinsics/index.html).
+
+Most of them are marked as experimental, unstable and useable in nightly versions of the compiler.


I would have expected some discussion of std::arch, the "SIMD and vendor intrinsics module".

I know that most usage is behind crates which use std::arch, but given the level we're working at in safety-critical software, we sometimes need to drop down to that level of specificity.

Do you think it's useful to include a std::arch discussion here and how unsafe factors in?

I think simd should be a separate chapter.

This chapter can link to it.

Manishearth · 2025-02-14T07:43:02Z

.../initiatives/safe-use-of-unsafe-guidelines/learn_unsafe_rust/src/core_unsafety/intrinsics.md

+
+# Intrinsics
+
+Rust provides a set of compiler intrinsics as part of `core` and `std` respectively (https://doc.rust-lang.org/std/intrinsics/index.html).


At a minimum I'd expect this chapter to go into some depth about what an intrinsic is, and how it is different from a regular function.

iglesias

Hello. I wrote suggestions to fix a few typos in case they may help.

iglesias · 2025-02-16T07:25:37Z

.../initiatives/safe-use-of-unsafe-guidelines/learn_unsafe_rust/src/core_unsafety/intrinsics.md

+
+Thus, the clear recommendation is not using the experimental compiler intrinsics in a safety-critical project.
+
+There are only few functions that are not marked as experimental: `copy`, `copy_nonoverlapping`, `write_bytes`, `transmute`.


Suggested change

There are only few functions that are not marked as experimental: `copy`, `copy_nonoverlapping`, `write_bytes`, `transmute`.

There are only a few functions that are not marked as experimental: `copy`, `copy_nonoverlapping`, `write_bytes`, `transmute`.

iglesias · 2025-02-16T07:25:45Z

.../initiatives/safe-use-of-unsafe-guidelines/learn_unsafe_rust/src/core_unsafety/intrinsics.md

+
+Rust provides a set of compiler intrinsics as part of `core` and `std` respectively (https://doc.rust-lang.org/std/intrinsics/index.html).
+
+Most of them are marked as experimental, unstable and useable in nightly versions of the compiler.


Suggested change

Most of them are marked as experimental, unstable and useable in nightly versions of the compiler.

Most of them are marked as experimental, unstable and usable in nightly versions of the compiler.

iglesias · 2025-02-16T07:26:01Z

.../initiatives/safe-use-of-unsafe-guidelines/learn_unsafe_rust/src/core_unsafety/intrinsics.md

+
+Most of them are marked as experimental, unstable and useable in nightly versions of the compiler.
+
+Many intrinsics are accessible though a stabilized API located elsewhere in the Standard or Core Library. The documentation for each intrinsic typically references the stabilized API.


Suggested change

Many intrinsics are accessible though a stabilized API located elsewhere in the Standard or Core Library. The documentation for each intrinsic typically references the stabilized API.

Many intrinsics are accessible through a stabilized API located elsewhere in the Standard or Core Library. The documentation for each intrinsic typically references the stabilized API.

Add statements.

c33f1b1

vapdrs reviewed Jan 21, 2025

View reviewed changes

vjonaswolf and others added 3 commits February 10, 2025 10:48

Update subcommittee/coding-guidelines/initiatives/safe-use-of-unsafe-…

ab3e76c

…guidelines/learn_unsafe_rust/src/core_unsafety/intrinsics.md Co-authored-by: Douglas Deslauriers <[email protected]>

Improve based on review comments.

bfb9b03

Merge branch 'guideline-on-intrinsics' of https://github.com/vjonaswo…

748c5b5

…lf/safety-critical-rust-consortium into guideline-on-intrinsics

vapdrs approved these changes Feb 12, 2025

View reviewed changes

PLeVasseur reviewed Feb 13, 2025

View reviewed changes

PLeVasseur added documentation Improvements or additions to documentation coding guidelines Related to work in the Coding Guidelines Subcommittee labels Feb 13, 2025

Manishearth reviewed Feb 14, 2025

View reviewed changes

iglesias reviewed Feb 16, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add statements on intrinsics. #148

Add statements on intrinsics. #148

vjonaswolf commented Jan 17, 2025

vjonaswolf commented Jan 17, 2025

PLeVasseur commented Jan 17, 2025

vapdrs left a comment •

edited

Loading

vapdrs Jan 21, 2025

PLeVasseur Feb 14, 2025

vapdrs left a comment

vjonaswolf commented Feb 12, 2025

PLeVasseur left a comment

PLeVasseur Feb 13, 2025

Manishearth Feb 14, 2025

Manishearth Feb 14, 2025

PLeVasseur Feb 13, 2025

Manishearth Feb 14, 2025

PLeVasseur Feb 14, 2025

PLeVasseur Feb 13, 2025

Manishearth Feb 14, 2025

PLeVasseur Feb 13, 2025

Manishearth Feb 14, 2025

Manishearth Feb 14, 2025

Manishearth Feb 14, 2025

iglesias left a comment

iglesias Feb 16, 2025

iglesias Feb 16, 2025

iglesias Feb 16, 2025


		Thus, the clear recommendation is not using the experimental compiler intrinsics in a safety-critical project.

		With `transmute` there is one major exception. However, `transmute` is handled in other parts of the guidelines.


		Most of them are marked as experimental, unstable and useable in nightly versions of the compiler.

		Many intrinsics are accessible though a stabilized API located elsewhere in the Standard or Core Library. The documentation for each intrinsic typically references the stabilized API.


		Rust provides a set of compiler intrinsics as part of `core` and `std` respectively (https://doc.rust-lang.org/std/intrinsics/index.html).

		Most of them are marked as experimental, unstable and useable in nightly versions of the compiler.


		# Intrinsics

		Rust provides a set of compiler intrinsics as part of `core` and `std` respectively (https://doc.rust-lang.org/std/intrinsics/index.html).


		Thus, the clear recommendation is not using the experimental compiler intrinsics in a safety-critical project.

		There are only few functions that are not marked as experimental: `copy`, `copy_nonoverlapping`, `write_bytes`, `transmute`.

	There are only few functions that are not marked as experimental: `copy`, `copy_nonoverlapping`, `write_bytes`, `transmute`.
	There are only a few functions that are not marked as experimental: `copy`, `copy_nonoverlapping`, `write_bytes`, `transmute`.

	Many intrinsics are accessible though a stabilized API located elsewhere in the Standard or Core Library. The documentation for each intrinsic typically references the stabilized API.
	Many intrinsics are accessible through a stabilized API located elsewhere in the Standard or Core Library. The documentation for each intrinsic typically references the stabilized API.

Add statements on intrinsics. #148

Are you sure you want to change the base?

Add statements on intrinsics. #148

Conversation

vjonaswolf commented Jan 17, 2025

vjonaswolf commented Jan 17, 2025

PLeVasseur commented Jan 17, 2025

vapdrs left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vapdrs left a comment

Choose a reason for hiding this comment

vjonaswolf commented Feb 12, 2025

PLeVasseur left a 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

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

iglesias left a 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

vapdrs left a comment •

edited

Loading