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.

Clef Language Attributes

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

NORMATIVE: The F# [<AutoOpen>] attribute is rejected by CCS. Module re-exports SHALL be explicit; an open declaration in the consuming file is required to bring module contents into scope. This eliminates implicit-scope-injection behavior that complicates name resolution and code review. Code that applies [<AutoOpen>] is not Clef-conformant; CCS reports a diagnostic and rejects the input.

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 one of the tools that keeps a scope-bounded value valid at its use site.

Storage follows lifetime class, not the fact of escaping: A value’s storage is selected by its lifetime class, not by a binary “does it escape” test. There are four lifetime classes, and a value that outlives its defining scope does not automatically need the heap. See Closure Representation §2.3, §3.3 for the authoritative model.

1. scope-bounded rides the stack (memref.alloca); it is valid only while the defining frame is alive.
2. region-bounded lives in a region or arena and is valid for the region’s extent.
3. program-lifetime goes to static storage: mutable in Sram, immutable in Flash, emitted as a memref.global (.bss). It is constructed once, held to program end, and never freed. This is not the heap.
4. genuinely-dynamic goes to the heap. On a freestanding no-heap target this class does not exist, so a value that classifies as dynamic there is a compile-time lifetime error, not a silent heap allocation.

inline addresses class 1. A scope-bounded stack buffer that a function returns a view into would dangle once the frame is deallocated; expanding the body at the call site lifts the buffer into the caller’s frame so the view stays valid. A value that instead escapes to program lifetime does not need inlining or the heap. It classifies as program-lifetime and goes to static storage.

The scope-bounded escape: A function fills a scope-bounded stack buffer and returns a string view over it. When the function returns, the frame is deallocated and the view dangles.

// WITHOUT inline - the view escapes a scope-bounded buffer and dangles
let readln () : string =
    let buffer = Array.zeroCreate<byte> 256      // scope-bounded, in readln's frame
    let len = readLineInto buffer 256
    String.ofUtf8 buffer[0 .. len - 1]           // view over readln's stack buffer!
    // When readln returns, buffer is deallocated - the view is now INVALID

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

Lifting the buffer with inline: Marking the function inline causes CCS to expand the body at the call site, lifting the scope-bounded buffer into the caller’s frame:

// WITH inline - the buffer is lifted to the caller's frame
let inline readln () : string =
    let buffer = Array.zeroCreate<byte> 256
    let len = readLineInto buffer 256
    String.ofUtf8 buffer[0 .. len - 1]

let hello() =
    // AFTER inline expansion, semantically becomes:
    let buffer = Array.zeroCreate<byte> 256      // Now in hello's frame!
    let len = readLineInto buffer 256
    let name = String.ofUtf8 buffer[0 .. len - 1]  // view valid through hello's scope
    greet name                                      // Safe - hello's frame is alive
 

When to Use inline for Escape Analysis:

inline applies to the scope-bounded class. Mark a function inline when it:

1. Fills a scope-bounded stack buffer (a bounded stack array)
2. Returns a reference, view, or fat pointer (like string) over that buffer
3. Has a caller that needs the returned value to remain valid past the call

This pattern is common in platform libraries (e.g., Console.readln) where the implementation detail of stack buffering should be transparent to application code. A value that instead needs to outlive every caller is not a candidate for inlining: it classifies as program-lifetime and is placed in static storage, or as region-bounded and placed in an arena.

Design Note: This mechanism supports Level 1 (Implicit) memory management from the Memory Regions design - developers write standard F# code while the compiler places each value by its lifetime class. Inline expansion is the tool for the scope-bounded class; static storage and arenas cover values that outlive their defining scope.

Entry Point Attribute

Platform Binding Notes

Clef Note: Clef does not use DllImport or P/Invoke. Platform operations use CCS intrinsics (Sys.write, Mmio.store, etc.) which are recognized by module pattern and compiled to platform-specific code. Register access uses the width-typed Mmio handle; there is no user-facing raw-pointer store. 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:

Clef Note: Clef has no user-denotable raw-pointer surface. nativeptr<'T>, voidptr, NativePtr.*, and the fixed/stackalloc/&& forms are not available in Clef source, neither in interior code nor at a binding boundary. Raw-pointer kinds exist only as internal, non-user-denotable compiler plumbing. Use the sanctioned surface instead: a bounded stack array for a buffer, the width-typed Mmio handle for a register, Ptr<'T, 'Region, 'Access> or an opaque CHandle for a pointer returned from a C binding, and the flat closure as the interior pointer mechanism. On a freestanding no-heap target there is no FFI leg (no libc, no malloc), so no binding-boundary pointer arises there at all.

Pointer Types with Access Kinds

Clef expresses a memory reference with region and access annotations rather than a raw pointer:

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.