[Coding Guideline]: Ensure reads of union fields produce valid values

[manhatsu]

Added new guideline on unions by @rcseacord.

This is the same content as #270 but moved to the feature branch.

[netlify]

✅ Deploy Preview for scrc-coding-guidelines ready!

Name	Link
🔨 Latest commit	945d8f0
🔍 Latest deploy log	https://app.netlify.com/projects/scrc-coding-guidelines/deploys/694c9afa434667000815c7f1
😎 Deploy Preview	https://deploy-preview-300--scrc-coding-guidelines.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[rcseacord]

@PLeVasseur @felix91gr I did a final cleanup and this rule LGTM. Please review & approve

[iglesias]

I left a couple of comments. Otherwise it was all clear. One is a question about a line I wasn't sure about and the other just a typo fix suggestion.

[felix91gr]

@PLeVasseur @felix91gr I did a final cleanup and this rule LGTM. Please review & approve

Alright, it goes into the queue.

[PLeVasseur]

@PLeVasseur @felix91gr I did a final cleanup and this rule LGTM. Please review & approve

Alright, it goes into the queue.

Hey @felix91gr -- did you take a look at this one yet? I'd like it to be reviewed before we queue it up

(I'll try to make time to review some of @rcseacord's latest ones tomorrow, this included, if it's not been reviewed by you yet)

[felix91gr]

I'd like it to be reviewed before we queue it up

@PLeVasseur ah, sorry! I forgot we have a Merge Queue as well. I meant it as my own task queue, my bad. I haven't reviewed it yet

[PLeVasseur]

Hey thanks for pulling this together @manhatsu and @rcseacord

Given that adding the bibliography bit touches quite a few other things, I'd suggest backing that out of this PR if you'd like the guideline to be reviewed on its merits and merged sooner than later.

I've opened issue #306 to track the work towards the work for a bibliography.

[manhatsu]

There is a duplication of URL in these two documents:
expressions/gui_Bib7x9KmPq2nL.rst.inc and types-and-traits/gui_0cuTYG8RVYjg.rst.inc.
bibliography.md says I should consider this, but how can I actually solve this?
I think it's fine if both have the source entry...

[PLeVasseur]

There is a duplication of URL in these two documents: expressions/gui_Bib7x9KmPq2nL.rst.inc and types-and-traits/gui_0cuTYG8RVYjg.rst.inc. bibliography.md says I should consider this, but how can I actually solve this? I think it's fine if both have the source entry...

Yeah, you're right. I didn't have this implemented correctly. Duplicate URLs should be fine, what I wanted to have was for the same URL to force consistent referencing to be used.

I've pushed #335 which should fix this.

Please take a look at the following and rebase:
https://github.com/rustfoundation/safety-critical-rust-coding-guidelines/blob/main/docs/bibliography.md

[PLeVasseur]

I rebased this on main. It's building and working now.

[PLeVasseur]

This is somewhat a procedural review to get this in-line with current best practices as outlined in CONTRIBUTING.md.

I haven't reviewed the contents of the guideline yet.

Please update and I can then take a look through content.

[PLeVasseur]

@guidelines-bot /claim

[github-actions]

✅ @PLeVasseur has claimed this review (previously: @PLeVasseur, @felix91gr).

[PLeVasseur]

Okay, have now reviewed the contents.

Overall this looks really good.

Please take a look at the comments and suggestions I left.

[PLeVasseur]

How about this? The goal is to show this in a situation / light that mimics code we might see used.

1. We make the union #[repr(C)] as most of the time we'll be doing this to interact over FFI
2. We put // SAFETY: comments above usages of unsafe; still kept in there that we're therefore compliant
3. We use assert_eq!() instead of println!() so that we can test for equivalence

#[repr(C)]
#[derive(Copy, Clone)]
union IntOrBoolData {
    i: u8,
    b: bool,
}

/// Tracks which field of the union is currently active.
#[derive(Clone, Copy, PartialEq, Eq)]
enum ActiveField {
    Int,
    Bool,
}

/// A union wrapper that tracks the active field at runtime.
pub struct IntOrBool {
    data: IntOrBoolData,
    active: ActiveField,
}

impl IntOrBool {
    pub fn from_int(value: u8) -> Self {
        Self {
            data: IntOrBoolData { i: value },
            active: ActiveField::Int,
        }
    }

    pub fn from_bool(value: bool) -> Self {
        Self {
            data: IntOrBoolData { b: value },
            active: ActiveField::Bool,
        }
    }

    pub fn set_int(&mut self, value: u8) {
        self.data.i = value;
        self.active = ActiveField::Int;
    }

    pub fn set_bool(&mut self, value: bool) {
        self.data.b = value;
        self.active = ActiveField::Bool;
    }

    /// Returns the integer value if that field is active.
    pub fn as_int(&self) -> Option<u8> {
        match self.active {
            // SAFETY: We only read `i` when we know it was last written as `i`, thus compliant
            ActiveField::Int => Some(unsafe { self.data.i }),
            ActiveField::Bool => None,
        }
    }

    /// Returns the boolean value if that field is active.
    pub fn as_bool(&self) -> Option<bool> {
        match self.active {
            // SAFETY: We only read `b` when we know it was last written as `b`, thus compliant
            ActiveField::Bool => Some(unsafe { self.data.b }),
            ActiveField::Int => None,
        }
    }
}

fn main() {
    let mut value = IntOrBool::from_bool(true);
    assert_eq!(value.as_bool(), Some(true));
    assert_eq!(value.as_int(), None);

    value.set_int(42);
    assert_eq!(value.as_bool(), None);
    assert_eq!(value.as_int(), Some(42));
}

[rcseacord]

Does this program have to do something so it's not all optimized away? Maybe return value?

[rcseacord]

I guess it doesn't matter. It's hard to make this code do something meaningful. A good optimizer is just going to return a constant value.

[rcseacord]

resolved by d70df8d

[felix91gr]

Does this program have to do something so it's not all optimized away?

Assertions are never optimized away, by design. So whatever this program asserts, it will always be tested.

[rcseacord]

OK, there are also debug assertions that are removed from the release build.

[PLeVasseur]

How about this?

1. We make the union #[repr(C)] as most of the time we'll be doing this to interact over FFI
2. We put // SAFETY: comments above usages of unsafe; still kept in there that we're therefore compliant
3. We use assert_eq!() instead of println!() so that we can test for equivalence

#[repr(C)]
union IntOrBool {
    i: u8,
    b: bool,
}
fn main() {
    let u = IntOrBool { b: true };
    
    // SAFETY: Read the same field that was written, thus compliant
    assert_eq!(unsafe { u.b }, true); // compliant
}

[PLeVasseur]

Nice, thanks for the revisions.

LGTM