Special Attributes and Types

This chapter describes attributes and types that have special significance to the Clef compiler.

Clef Note: Clef does not use CLI assemblies or the .NET runtime. Attributes related to assembly metadata, P/Invoke interop, serialization, and runtime reflection are not applicable. This chapter covers only those attributes meaningful for native compilation.

Custom Attributes Recognized by Clef

The following custom attributes have special meanings recognized by the Clef compiler.

F# Language Attributes

These attributes control F# language semantics and are fully supported:

Memory and Layout Attributes

These attributes control memory layout for native compilation:

Clef Note: The StructLayout and FieldOffset attributes are critical for defining types that must match specific memory layouts, such as hardware register descriptors or wire protocol structures. See Memory Regions for memory placement semantics.

Inline and Optimization Attributes

Inline Functions and Escape Analysis

In Clef, the inline keyword has additional semantic significance beyond performance optimization. When a function is marked inline, CCS (Clef Compiler Service) captures its body for transparent expansion at call sites. This is critical for escape analysis of stack-allocated memory.

The Escape Problem: When a function allocates memory via NativePtr.stackalloc and returns a pointer to that memory, the pointer becomes invalid when the function returns (the stack frame is deallocated).

// WITHOUT inline - pointer escapes and dangles
let readln () : string =
    let buffer = NativePtr.stackalloc<byte> 256  // Allocated in readln's frame
    let len = readLineInto buffer 256
    NativeStr.fromPointer buffer len             // Returns pointer to readln's stack!
    // When readln returns, buffer is deallocated - pointer is now INVALID

let hello() =
    let name = readln()  // name points to deallocated memory!
    greet name           // Undefined behavior

The Solution: Marking the function inline causes CCS to expand the function body at the call site, lifting the allocation to the caller’s frame:

// WITH inline - allocation lifted to caller's frame
let inline readln () : string =
    let buffer = NativePtr.stackalloc<byte> 256
    let len = readLineInto buffer 256
    NativeStr.fromPointer buffer len

let hello() =
    // AFTER inline expansion, semantically becomes:
    let buffer = NativePtr.stackalloc<byte> 256  // Now in hello's frame!
    let len = readLineInto buffer 256
    let name = NativeStr.fromPointer buffer len  // Pointer valid through hello's scope
    greet name                                    // Safe - hello's frame is alive

When to Use inline for Escape Analysis:

Functions should be marked inline when they:

1. Allocate memory via NativePtr.stackalloc or Arena.alloc
2. Return a pointer, reference, or fat pointer (like string) to that memory
3. The caller needs the returned value to remain valid

This pattern is common in platform libraries (e.g., Console.readln) where the implementation detail of stack allocation should be transparent to application code.

Design Note: This mechanism supports Level 1 (Implicit) memory management from the Memory Regions design - developers write standard F# code while the compiler ensures memory safety through inline expansion.

Entry Point Attribute

Platform Binding Notes

Clef Note: Clef does not use DllImport or P/Invoke. Platform operations use CCS intrinsics (Sys.write, NativePtr.set, etc.) which are recognized by module pattern and compiled to platform-specific code. External library bindings use quotation semantic carriers. See Platform Bindings.

Memory Region Attributes

These attributes control memory placement in Clef:

Example of peripheral descriptor usage:

[<PeripheralDescriptor("GPIO", 0x48000000UL)>]
type GPIO_TypeDef = {
    [<Register("MODER", 0x00u, "rw")>]
    MODER: Ptr<uint32, peripheral, readWrite>

    [<Register("IDR", 0x10u, "r")>]
    IDR: Ptr<uint32, peripheral, readOnly>

    [<Register("ODR", 0x14u, "rw")>]
    ODR: Ptr<uint32, peripheral, readWrite>
}

Custom Attributes Emitted by Clef

The Clef compiler emits the following information as part of compilation:

Clef Note: Debug information is provided through native debug formats (DWARF on Linux/macOS, PDB on Windows).

Attributes Not Applicable to Clef

The following attribute categories from managed F# are not applicable to Clef compilation:

Assembly Attributes

Assembly metadata attributes (AssemblyVersion, AssemblyTitle, AssemblyCompany, etc.) are not applicable as Clef produces native binaries, not CLI assemblies.

P/Invoke and Interop Attributes

Serialization Attributes

Reflection and Type Provider Attributes

Threading Attributes

Error Conditions in Clef

Clef Note: Clef uses the Result<'T, 'E> type for explicit error handling rather than exceptions. Operations that can fail return Result values. The following describes how traditional exception scenarios are handled.

Arithmetic Errors

Array and Memory Errors

Type Errors

Stack Overflow

Stack overflow can occur with deeply recursive functions. Clef provides:

• Tail call optimization to prevent stack growth for tail-recursive functions
• Compile-time analysis to warn about potentially unbounded recursion
• Platform-specific stack size configuration

Clef Note: The absence of NullReferenceException, InvalidCastException, and similar runtime type errors is a fundamental property of Clef’s null-free, statically verified type system.

Platform-Specific Types

Clef provides the following types for platform interaction:

Pointer Types with Access Kinds

Clef extends pointer types with access kind annotations:

type Ptr<'T, 'Region, 'Access> = ...

Where:

• 'T is the pointed-to type
• 'Region is a phantom type indicating memory region (stack, arena, peripheral, sram, flash)
• 'Access is a phantom type indicating access permissions (readOnly, writeOnly, readWrite)

See Access Kinds for details on access annotations.