diff --git a/subcommittee/coding-guidelines/initiatives/safe-use-of-unsafe-guidelines/safe-use-of-unsafe-guidelines-proposal.md b/subcommittee/coding-guidelines/initiatives/safe-use-of-unsafe-guidelines/safe-use-of-unsafe-guidelines-proposal.md index d90abfd..af46245 100644 --- a/subcommittee/coding-guidelines/initiatives/safe-use-of-unsafe-guidelines/safe-use-of-unsafe-guidelines-proposal.md +++ b/subcommittee/coding-guidelines/initiatives/safe-use-of-unsafe-guidelines/safe-use-of-unsafe-guidelines-proposal.md @@ -51,7 +51,10 @@ The Rust project has also produced the Rustonomicon, which goes at some places i SAE International’s JA1020 (WIP) is also ongoing work in this space \[3\]. +The Learn unsafe Rust book (WIP) \[4\]. + \[1\]: [https://rust-lang.github.io/unsafe-code-guidelines/](https://rust-lang.github.io/unsafe-code-guidelines/) \[2\]: [https://doc.rust-lang.org/nomicon/](https://doc.rust-lang.org/nomicon/) \[3\]: [https://www.sae.org/standards/content/ja1020/](https://www.sae.org/standards/content/ja1020/) +\[4\]: [https://github.com/google/learn_unsafe_rust](https://github.com/google/learn_unsafe_rust/) diff --git a/subcommittee/coding-guidelines/initiatives/safe-use-of-unsafe-guidelines/unsafe-example-usage.md b/subcommittee/coding-guidelines/initiatives/safe-use-of-unsafe-guidelines/unsafe-example-usage.md new file mode 100644 index 0000000..0b93c48 --- /dev/null +++ b/subcommittee/coding-guidelines/initiatives/safe-use-of-unsafe-guidelines/unsafe-example-usage.md @@ -0,0 +1,89 @@ +# Examples of `unsafe` to work into chapter + +The following are examples of `unsafe` code usage we could use to work into a chapter of the [Learn unsafe Rust](https://github.com/google/learn_unsafe_rust) book. These are not exhaustive, but give a starting point for something of a practicum for using `unsafe`. + +## Example 1 + +```rust +#![deny(unsafe_op_in_unsafe_fn)] + +use std::slice::from_raw_parts_mut; + +/// # Panics +/// +// Panics if mid point is not in slice +fn split_at_mut<'a, T>(slice: &'a mut [T], mid: usize) + -> (&'a mut [T], &'a mut [T]) { + assert!(0 <= mid && mid <= slice.len()); + + /// SAFETY: + /// + /// * split_at_mut_unchecked expects 0 <= mid <= len + /// * we just asserted that + unsafe { split_at_mut_unchecked(slice, mid) } +} + +/// # Safety (1) +/// +/// * Caller needs to ensure the mid point is actually in the slice +/// * 0 <= mid <= slice.len() +// (2) `unchecked` is Rust standard lingo +// (3) unsafe functions express pre-conditions to the caller +unsafe fn split_at_mut_unchecked<'a, T>(slice: &'a mut [T], mid: usize) + -> (&'a mut [T], &'a mut [T]) { + + // (4) It's still useful to express our pre-conditions in unsafe functions + // as a debug_assert! + debug_assert!(0 <= mid && mid <= slice.len()); + + let ptr = slice.as_mut_ptr(); + let len = slice.len(); + + // SAFETY: (5) SAFETY ARGUMENTS + // + // * Caller has to ensure 0 <= mid <= len + // * (ptr, mid) , (ptr.add(mid), len-mid) don't overlap + // * Therefore, no aliasing + unsafe { // (6) unsafe blocks and their role + (from_raw_parts_mut(ptr, mid), // (7) unsafe interface of libcore + from_raw_parts_mut(ptr.add(mid), len - mid)) + } + // (8) unsafe blocks must be reviewed with the whole module in mind + // (9) unsafety has interplay with visibility +} + +fn conjure_non_null() { + let mut val = 4; + let ptr = &raw mut val; + let non_null: std::ptr::NonNull<_> = + unsafe { std::ptr::NonNull::new_unchecked(ptr) }; +} +``` + +## Example 2 + +```rust +// (10) interactions between fields +// (11) fields with interactions have to be private +// (12) seperate unsafe bits from safe bits and hide them in visibility +pub struct RawVec { + // points of allocation if cap > 0 + // should never be read on cap = 0 + ptr: NonNull<*mut T>, + // cap >= len + // cap represents the actual allocation + cap: usize, +} + +impl RawVec { + unsafe fn set_cap(self: &mut Vec, cap: usize) { + self.cap = cap; + } +} + +pub struct Vec { + raw: RawVec, + // len <= cap + len: usize, +} +``` diff --git a/subcommittee/coding-guidelines/meetings/19-November-2024/agenda.md b/subcommittee/coding-guidelines/meetings/19-November-2024/agenda.md index ae4076b..10545d1 100644 --- a/subcommittee/coding-guidelines/meetings/19-November-2024/agenda.md +++ b/subcommittee/coding-guidelines/meetings/19-November-2024/agenda.md @@ -2,12 +2,15 @@ ## Agenda +0. Meeting recordings / transcriptions - Live discussion 1. Acceptance of Previous Meeting Minutes 2. Shift meeting time 2 hours earlier to accomodate Asia participants (Pete LeVasseur) 3. Contributor Expectations - Approval (Pete LeVasseur) 4. Safe Usage of Unsafe Guidelines - Check-in (Pete LeVasseur) + * [Learn `unsafe` Rust](https://github.com/google/learn_unsafe_rust) - Offline Review & Q&A + * [Examples of unsafe patterns](../../initiatives/safe-use-of-unsafe-guidelines/unsafe-example-usage.md) - Chapter writeup 5. MISRA + Rust (Alex Celeste) -7. Round table +6. Round table Supplemental material to the agenda can be found on the [GitHub repo](https://github.com/rustfoundation/safety-critical-rust-consortium/tree/main/subcommittee/coding-guidelines).