The Hat Principle
The Hat Principle is the foundational design philosophy behind Toka's memory safety model. Rather than forcing developers to write complex lifetime annotations (as in Rust) or relying on a runtime Garbage Collector (as in Go or Java), Toka introduces visible syntactic tokens called "Hats" to track ownership, resource lifetimes, and access permissions at compile time.
What is a Hat?
In Toka, a Hat is a syntactic sigil (symbol) attached directly to an identifier. This explicit notation tells both the programmer and the compiler's safety analysis engine exactly how a resource is stored, owned, and accessed.
Toka defines four primitive Hat typologies:
| Hat Sigil | Typology | Semantic Description | Allocation Context |
|---|---|---|---|
* | Raw Pointer | Unsafe, low-level pointer with manual lifecycle management | Heap or Address-of |
^ | Unique Pointer | Safe, exclusive ownership of a heap-allocated resource (Auto-free) | Heap (new) |
~ | Shared Pointer | Safe, reference-counted shared ownership | Heap (new) |
& | Borrow Pointer | Safe, compile-time borrow/reference to another soul's data | Existing Soul |
Handle vs. Soul: Implicit Dereferencing
One of the key usability features of the Hat Principle is the strict bifurcation between a pointer's container and its underlying data:
- Handle (The Hat): An identifier with its sigil (
^ptr,*ptr,~ptr) represents the pointer container itself (the metadata holding the address). - Soul (The Data): An identifier without its sigil (
ptr) represents the underlying data (the actual value).
By operating directly on the Soul (omitting the sigil), Toka completely eliminates the need for explicit dereferencing operators like C's *p or Rust's *p. For example, ptr.x = 42 directly mutates the underlying heap data without manual dereferencing.
The Pointer Analysis Layer (PAL)
The compiler's Pointer Analysis Layer (PAL) Checker inspects Hat configurations during compilation to statically enforce strict safety guarantees:
- Strict Move Semantics: A Unique Pointer (
^) automatically transfers ownership on assignment. The PAL Checker blocks any "use-after-move" of the original handle. - Deterministic Destruction: When an owned pointer (
^or the last~) exits its declared scope, its resource is automatically freed. - Rigorous Borrow Checking: Borrow Pointers (
&) are checked to ensure they never outlive the underlying Soul, preventing dangling references. - Data Race Prevention: The PAL Checker ensures that mutable access (
#) is exclusive, while shared access is read-only.
Learning Path
To master the Hat Principle, explore the following sections in order:
- Soul & Identity: Master the Handle/Soul split, implicit dereferencing, and the syntax of member borrowings (including standard parentheses and Hat-Terminal Morphology).
- Ownership & Hats: Explore the four ownership models, default moves versus copying, the
cedekeyword, and the visual distinction between mutable local declarations and mutable method call receivers. - Memory Safety & PAL: Deep dive into the Pointer Analysis Layer and see how Toka achieves zero-overhead compile-time memory safety.