Advanced Topics

What is "Raw & Unsafe"?

Zith's safety model handles 95% of use cases. The raw and unsafe features are reserved for situations where you need:

1. FFI (Foreign Function Interface) — Calling C libraries directly
2. Raw pointer arithmetic — Custom memory layouts and allocators
3. Inline assembly — Platform-specific optimizations
4. Custom allocators — Building your own memory management

Key Concepts

unsafe Blocks

Code inside an unsafe block bypasses Zith's safety checks:

unsafe {
    // All code here bypasses safety checks
    let ptr = 0x1000 as *u8;
    *ptr = 42;  // Direct memory write
}

Raw Functions

Functions declared with raw fn allow unsafe operations in their body:

raw fn readRegister(addr: opaque): u32 {
    let ptr = addr as *u32;
    *ptr
}

The Trust Capability

Trust lets you expose safe wrappers over unsafe internals:

trait MMIONode extends Trust {
    raw fn read(self, offset: u64): u32 {}
    raw fn write(self, offset: u64, val: u32) {}
}

fn safeCopy(src: view MMIONode, dst: lend MMIONode) {
    let v = src.read(0x00);
    dst.write(0x00, v);
}

When to Use Raw & Unsafe

Appropriate uses:

• Writing FFI bindings for C libraries
• Implementing custom allocators or data structures
• Performance-critical code with proven safety
• Inline assembly for hardware access

Avoid when:

• Safe Zith constructs would work
• You're not certain about memory invariants
• The code will be frequently modified
• Safety can be guaranteed at runtime instead

Topics in This Section

Safety Guidelines

1. Minimize unsafe scope — Keep unsafe {} blocks as small as possible
2. Document invariants — Explain why the unsafe code is safe
3. Add runtime checks — Validate inputs before entering unsafe blocks
4. Write tests — Especially for unsafe code paths
5. Review carefully — Unsafe code requires extra scrutiny

Example: Safe Wrapper Around Unsafe Code

fn getElement(arr: view [i32], index: usize): ?i32 {
    if (index >= arr.len()) ? none
    arr[index]
}

Next Steps

• Learn how to use raw and unsafe features responsibly
• Dive into raw pointers for memory manipulation
• Understand unsafe operations in detail