#unsafe #safety #proc-macro #documentation

macro safety-guard

#[safety] attribute to generate a corresponding doc entry and a debug assertion if a constraint is specified

9 releases

✓ Uses Rust 2018 edition

0.1.9 Apr 6, 2019
0.1.8 Apr 6, 2019
0.1.6 Mar 19, 2019

#61 in Debugging

Download history 52/week @ 2019-03-09 23/week @ 2019-03-16 66/week @ 2019-03-23 4/week @ 2019-03-30 63/week @ 2019-04-06 14/week @ 2019-04-13 25/week @ 2019-04-20 6/week @ 2019-04-27 61/week @ 2019-05-04

53 downloads per month

MIT/Apache

11KB
131 lines

Adds a #[safety] attribute for functions. The attribute adds a # Safety section to the documentation of the function and tests the given constraints in debug builds.

The attribute has four different forms:

  • #[safety("Description")]: Only the description is included in the documentation.
  • #[safety(assert(constraint), "Description")]: constraint must evaluate to true.
  • #[safety(eq(lhs, rhs), "Description")]: lhs and rhs needs to be equal
  • #[safety(ne(lhs, rhs), "Description")]: lhs and rhs must not be equal

A function with a #[safety] attribute must be marked as unsafe. Otherwise a compile error is generated.

If # Safety already exists in the documentation, the heading is not added.

Examples

#[safety(assert(lhs.checked_add(rhs).is_some()), "`lhs` + `rhs` must not overflow")]
unsafe fn add_unchecked(lhs: usize, rhs: usize) -> usize {
    lhs + rhs
}

generates

/// # Safety
/// - `lhs` + `rhs` must not overflow
unsafe fn add_unchecked(lhs: usize, rhs: usize) -> usize {
    debug_assert!(lhs.checked_add(rhs).is_some(), "`lhs` + `rhs` must not overflow");
    lhs + rhs
}

Without a constraint, only the documentation is added:

#[safety("`hash` must correspond to the `string`s hash value")]
unsafe fn add_string_with_hash(string: &str, hash: u64) -> u64 {
    // ...
}

generates

/// # Safety
/// - `hash` must correspond to the `string`s hash value
unsafe fn add_string_with_hash(string: &str, hash: u64) -> u64 {
    // ...
}

It is also possible to use multiple #[safety] attributes:

#[safety(eq(ptr as usize % layout.align(), 0), "`layout` must *fit* the `ptr`")]
#[safety(assert(new_size > 0), "`new_size` must be greater than zero")]
#[safety(
    "`new_size`, when rounded up to the nearest multiple of `layout.align()`, must not \
    overflow (i.e., the rounded value must be less than `usize::MAX`)."
)]
unsafe fn realloc(
    ptr: *mut u8,
    layout: Layout,
    new_size: usize,
) -> *mut u8 {
    // ...
}

However, the documentation is generated in reversed order:

/// # Safety
/// - `new_size`, when rounded up to the nearest multiple of `layout.align()`, must not
///   overflow (i.e., the rounded value must be less than `usize::MAX`).
/// - `new_size` must be greater than zero
/// - `layout` must *fit* the `ptr`
unsafe fn realloc(
    ptr: *mut u8,
    layout: Layout,
    new_size: usize,
) -> *mut u8 {
    debug_assert!(new_size > 0, "`new_size` must be greater than zero");
    debug_assert_eq!(ptr as usize % layout.align(), 0, "`layout` must *fit* the `ptr`");
    // ...
}

Dependencies

~773KB
~17K SLoC