[−][src]Crate unsafety

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.

IMPLEMENTS_CONTAINER	Implements a container type, such as `Vec`, `HashMap`, etc.
IMPLEMENTS_DEVICE_DRIVER	The unsafe code is part of a device driver implementation. It must be able to directly access memory. For example, it needs to be able to directly access memory-mapped I/O registers (MMIO).
IMPLEMENTS_MEMORY_MANAGER	The unsafe code is part of the implementation of a memory manager, such as a heap or a page table. This is distinct from `ImplementsContainer` because a container implementation uses a memory manager, but is not part of the implementation of a memory manager.
IMPLEMENTS_SAFE_TRANSMUTE	The unsafe code safely implements a legal type conversion that cannot currently be expressed in Rust's type system.
PERFORMANCE	The unsafe code safely implements an algorithm that requires maximum performance. It is responsible for ensuring bounds checks, overflow checks, etc. have been performed.
USED_BY_FOREIGN_CODE	The unsafe code is called by foreign code (such as C code). The unsafe code is necessary in order to correctly exchange data and control flow with the calling code.
USES_FOREIGN_CODE	The unsafe code calls foreign code (such as C code). Such code cannot be verified by Rust's safety rules, and hence is unsafe.
USES_VECTOR_INTRINSICS	The unsafe code uses processor-specific intrinsics, such as vector (SIMD) intrinsics. Some of these intrinsics are marked `unsafe` because they are not guaranteed to be present in all processors. (For example, SSE 4.) Using an intrinsic instruction on a processor that does not implement the intrinsic is undefined behavior.

Functions

unsafe_reason

This function does nothing. It exists only so that the unsafe_because macro can verify that the reasons given to it are syntactically valid.