In this lesson, you will learn how to manually signal to the Rust compiler that your type upholds specific behavioral invariants that cannot be automatically verified by the borrow checker.
Why Traits Need the unsafe Keyword
Normally, Rust’s type system guarantees memory safety. However, some traits rely on contracts that exist outside the language's formal rules. When you define a trait as unsafe trait, you are telling the compiler: "Implementing this trait requires the developer to manually ensure certain safety invariants."
If you implement such a trait, you must preface the implementation block with the unsafe keyword. By doing this, you are taking personal responsibility for the safety of any code that relies on that trait’s contract.
Example: The Send and Sync Markers
The most common examples are the marker traits Send and Sync. If you create a custom pointer wrapper that interacts with raw hardware or an external memory space, the compiler cannot know if it is thread-safe. If you are certain your implementation handles concurrent access safely (perhaps via internal atomics or hardware locking), you must explicitly opt-in:
struct RawHardwarePointer(*mut u8);
// We verify that access to this pointer is synchronized
// through hardware-level semaphores.
unsafe impl Sync for RawHardwarePointer {}
unsafe impl Send for RawHardwarePointer {}
When to Use This
You only use unsafe trait implementations when you are defining your own unsafe trait or satisfying the requirements of a trait that the compiler identifies as unsafe. The compiler is essentially asking you to bypass its automatic verification because the logic depends on conditions—like hardware state, C library behavior, or non-Rust memory layouts—that are invisible to the static analyzer.
If you mark an implementation as unsafe without upholding the underlying invariants, you create a violation of Rust's safety guarantees, which will lead to undefined behavior. Always document the invariants you have verified in a comment above the implementation block.
Key Takeaway: Marking a trait implementation as unsafe is a formal assertion to the compiler that you have manually verified the type’s adherence to the safety contracts that the borrow checker cannot prove.