Explicit Compile-Time Execution Design

[tahadostifam]

Explicit Compile-Time Execution Design

Executive Summary

Cyrus introduces a clean separation between compile-time and runtime execution through explicit comptime functions, providing predictable metaprogramming capabilities while maintaining simplicity and clarity.

1. Core Philosophy

Principle of Explicit Separation

• Compile-time code is explicitly marked and executes during compilation
• Runtime code is the default and executes when the program runs
• No ambiguity about when code executes

Design Goals

1. Predictability: Developers know exactly when code runs
2. Simplicity: Clear mental model without context-dependent behavior
3. Performance: Aggressive compile-time optimization
4. Safety: Compile-time errors cannot affect runtime execution

2. Language Design

2.1 Function Classification

// RUNTIME FUNCTION (Default)
// - Executes when program runs
// - Can perform I/O, allocate memory, have side effects
fn process_data(input: string) Result {
    // Runtime logic here
    return analyze(input);
}

// COMPILE-TIME FUNCTION (Explicit)
// - Executes during compilation
// - Must be pure and deterministic
// - Returns types, constants, or compiler directives
comptime fn generate_type() type {
    // Compile-time logic here
    return struct {
        id: u64,
        name: string,
        // Fields can have compile-time computed defaults
        timestamp: u64 = @compile_time_unix_timestamp(),
    };
}

2.2 Key Characteristics

Aspect	Compile-Time Functions	Runtime Functions
Execution	During compilation	During program execution
Side Effects	None allowed	Allowed
Determinism	Required	Optional
I/O Operations	Compiler I/O only	System I/O allowed
Memory Allocation	Compiler heap only	System heap allowed
Callable From	Other comptime functions	Anywhere

3. Type System Integration

3.1 First-Class Types

// Types are values in comptime context
// Built-in meta-type
comptime Type = typeid; 

comptime fn create_vector_type(dims: int8) Type {
    return struct {
        coords: float32[dims],
        
        fn magnitude(self: Self) float32 {
            var sum: float32 = 0;
            for coord in self.coords {
                sum += coord * coord;
            }
            return sqrt(sum);
        }
    };
}

// Type generation at compile time
const Vector3 = create_vector_type(3);
const Vector4 = create_vector_type(4);

// Usage at runtime
var v3: Vector3 = Vector3{ coords: [1.0, 2.0, 3.0] };
print(v3.magnitude());  // Runtime computation

3.2 Generic Types vs. Generated Types

// GENERIC TYPE (Parametric polymorphism)
// - Single type definition, multiple instantiations
// - Type checking happens at instantiation
struct Container<T> {
    items: []T;
    
    fn get(self: Self, index: usize) Option<T> {
        if (index < self.items.len) {
            return .Some(self.items[index]);
        } else {
            return .None;
        }
    }
}

// COMPTIME-GENERATED TYPE
// - Custom type created at compile time
// - Can be specialized based on parameters
comptime fn make_smart_container(max_size: usize, is_thread_safe: bool) Type {
    if is_thread_safe {
        return struct { buffer: T[max_size], mutex: DefaultMutex };
    } else {
        return struct { buffer: T[max_size] };
    }
}

4. Use Cases and Examples

4.1 JSON Schema → Type Generation

comptime fn json_to_type(schema: JsonSchema) typeid {
    switch (schema.kind) {
        case .Object => {
            var fields: Field[] = {};
            for field_schema in schema.fields {
                fields.append(Field{
                    name: field_schema.name,
                    type: json_to_type(field_schema.type),
                });
            }
            return @makeStructOf(fields);
        },
        case .Array => {
            return json_to_type(schema.element_type)[];
        },
        case .String => {
            return @typeOf(char*);
        },
        case .Number => {
            return @typeOf(float64);
        },
        case .Boolean => {
            return @typeOf(bool);
        },
    };
}

// Compile-time type generation
const UserSchema = parse_json('{
    "name": "string",
    "age": "number",
    "email": "string?",
    "preferences": "Map<string, any>"
}');

const User = json_to_type(UserSchema);
// User is now: struct {
//     name: string,
//     age: f64,
//     email: ?string,
//     preferences: Map<string, any>
// }

5. Implementation Architecture

5.1 Compilation Pipeline

Source Code
    │
    ├── Compile-Time Phase
    │   ├── Parse comptime functions
    │   ├── Execute comptime evaluator
    │   ├── Generate types/constants
    │   └── Expand macros/metaprogramming
    │
    └── Runtime Phase
        ├── Generate machine code
        ├── Optimize runtime functions
        └── Link dependencies

5.2 Memory Model

// COMPILE-TIME MEMORY
// - Managed by compiler
// - Freed after compilation
// - Only for comptime execution

comptime fn compile_time_alloc(size: usize) void* {
    return @compiler_alloc(size);  // Compiler-managed heap
}

// RUNTIME MEMORY
// - Managed by program
// - Follows program's lifetime
// - Uses system allocator

fn runtime_alloc(size: usize) *any {
    return malloc(size);  // System heap
}

6. Advantages Over Implicit Models (like Zig)

6.1 Clear Separation of Concerns

• No context-dependent behavior: Same function always executes at same time
• Easier debugging: Compile-time errors stay in comptime context
• Better tooling: IDEs can clearly distinguish execution contexts

6.2 Predictable Performance

// In Zig-like implicit model:
fn fib(n: u32) u32 {
    return if n <= 1 then n else fib(n-1) + fib(n-2);
}

const x = comptime fib(30);  // Compile-time explosion!
const y = fib(5);            // Runtime call

// In Cyrus:
comptime fn compile_time_fib(n: u32) u32 {
    // Explicitly optimized for compile time
    return fib_impl(n);
}

fn runtime_fib(n: u32) u32 {
    // Optimized for runtime
    return iterative_fib(n);
}

6.3 Safety Guarantees

• Comptime purity: No unexpected side effects during compilation
• Deterministic builds: Same input always produces same output
• No runtime surprises: Compile-time failures cannot affect running programs

7. Limitations and Trade-offs

7.1 Code Duplication

// Trade-off: Sometimes need to implement twice
comptime fn compile_time_parse(json: string) Result {
    // Pure, deterministic parsing
    return parse_without_io(json);
}

fn runtime_parse(json: string) Result {
    // Can use I/O, system calls
    return parse_with_error_logging(json);
}

7.2 Learning Curve

• Developers must understand two execution models
• Need to decide which logic belongs where

7.3 Tooling Complexity

• Need separate debuggers for compile-time code
• Profiling tools must handle two execution contexts

8. Conclusion

Cyrus's explicit compile-time execution model offers:

1. Simplicity: Clear separation eliminates mental overhead
2. Predictability: Developers control exactly when code runs
3. Performance: Optimized code generation without runtime overhead
4. Safety: Compile-time errors contained within compilation phase

This design is particularly well-suited for:

• Systems programming
• Metaprogramming-heavy applications
• Code generation tools
• Performance-critical software

Appendix: Comparison with Other Languages

• Zig: Implicit comptime based on values
• C++: Template metaprogramming + constexpr
• Rust: Macros + const fn (hybrid approach)