Provides annotations for describing and auditing usages of unsafe code in Rust.

This crate has no effect on the compilation or runtime behavior of Rust code. Its purpose is to allow developers to annotate Rust code with information about why unsafe code is used, and to enable automated tools for auditing code bases that use unsafe code.

Instead of this:

unsafe {
    // Scary interop code:
    let ptr: *mut libc::c_void = allocate_foreign_object();
    use_foreign_object(ptr, 42);
    free_foreign_object(ptr);
}

Developers can do this:

use unsafety::{unsafe_because, USES_FOREIGN_CODE};

unsafe_because! {
    USES_FOREIGN_CODE => {
        // Scary interop code:
        let ptr: *mut libc::c_void = allocate_foreign_object();
        use_foreign_object(ptr, 42);
        free_foreign_object(ptr);
    }
}

Type safety and concurrency safety are the key benefits of Rust. Because these safety properties depend on all components in that system correctly respecting those properties, even unsafe code, it is crucial that unsafe code nevertheless be correct code. This crate is intended to help meet that goal, by allowing developers to describe why code does what it does, with respect to unsafe code, and to make it easy to audit those descriptions.

Annotating reasons

The unsafe_because macro requires you to give a reason, and it allows you to give additional, optional information. You can add the following to any invocation of unsafe_because. (All of these can be repeated.)

• reason.owner("foo"): Identifies an owner or expert in this part of the design.
• reason.bug("..."): An identifier in a bug-tracking system. This is typically a URL or a bug number.
• reason.link("http://..."): A link to any relevant web page, such as a design document.
• reason.tag("key", "value"): Allows you to specify arbitrary key-value pairs.

Reusing reasons

Instead of re-stating the same reason repeatedly, reasons can be defined as constants and reused. This is useful when a reason has annotations, which would be cumbersome to repeat at every usage. Example:

use unsafety::{UnsafeReason, IMPLEMENTS_DEVICE_DRIVER, unsafe_because};

const IMPLEMENTS_FANCY_NETWORK_DRIVER: UnsafeReason = IMPLEMENTS_DEVICE_DRIVER
    .bug("some_bug_link")
    .owner("foo")
    .owner("bar")
    .link("https://.../some_design_doc.html");

unsafe_because! {
    IMPLEMENTS_FANCY_NETWORK_DRIVER => {
        // ...
    }
}

unsafe_because! {
    IMPLEMENTS_FANCY_NETWORK_DRIVER => {
        // ... even more code ...
    }
}

Combining reasons

Sometimes a single unsafe block has more than reason for using unsafe code. If possible, developers should split such blocks into separate blocks and use separate justifications for them. However, at times that is not possible. unsafe_because! allows you to provide a list of reasons, within square brackets.

Example:

use unsafety::{PERFORMANCE, IMPLEMENTS_DEVICE_DRIVER, unsafe_because};

// Some code has more than one reason for requiring unsafe code.
unsafe_because! {
    [PERFORMANCE, IMPLEMENTS_DEVICE_DRIVER] =>
        println!("Super fast and scary (but correct) code goes here.");
}

TODO

• Improve the list of standard reasons.
• Auditing tools.
• Needs macros for defining unsafe traits and unsafe function signatures, not just unsafe code blocks.

Future direction

It is possible that some future version of Rust could verify that a particular set of usages of unsafe meet some requirement. For example, it might be useful to allow unsafe code for the reason of accessing a device driver, but no other reason, within a given crate. unsafe_because could allow developers to encode that knowledge now, rather than trying to re-discover that knowledge after a large, mature component has been developed.