Local Fault Handlers (LFH) & Structured Typed Exits

[dmitrykolchev]

Local Fault Handlers (LFH) & Structured Typed Exits

Title: Local Fault Handlers (LFH)
Status: Proposal
Target: C# Language Specification / .NET Runtime
Keywords: leave, on leave, control-flow, pattern-matching, zero-cost-abstraction
Related: Labeled break and continue Statements

1. Abstract

This proposal introduces Local Fault Handlers, a mechanism for strict, typed, and local control flow transfer. It is designed to replace the ambiguity of break in nested loops, the unsafety of goto, and the performance overhead of Exceptions when used for flow control.

The feature introduces the leave operator to interrupt execution and transfer control to a strictly typed on leave block defined at the end of the method scope. This block utilizes C# switch expression syntax for pattern matching, ensuring a clean separation of the "Happy Path" from edge cases while guaranteeing type safety and deterministic resource disposal.

2. Motivation

Modern imperative programming often struggles with complex control flow in three specific areas:

1. The "Nested Break" Problem: Breaking out of a switch statement nested within a loop requires boolean flags (bool keepLooping), labelled loops, or goto. All are verbose or error-prone.
2. Exception Overhead: Using Exceptions for logic control (e.g., ValidationException) incurs significant runtime costs (stack trace generation, unwinding).
3. Return Code Pollution: The "Result Pattern" (returning Result<T>) forces developers to check if (result.IsFailure) return result; after every operation, obscuring the primary algorithm.

LFH solves these issues by treating local exits not as system failures, but as Typed State Transitions. It provides the performance of a jump instruction with the safety of a compiler-checked switch.

3. Detailed Design

3.1. The leave Operator

The leave operator terminates the current block of execution and transfers control to the method's on leave section. It accepts a payload, which can be a Nominal Type (class/struct) or a Structural Type (ValueTuple).

// Syntax
leave <expression>;

// Usage Examples:
leave (404, "Not Found");      // Structural (ValueTuple)
leave new ErrorState("Auth");  // Nominal (Record/Struct)

3.2. The on leave Handler

The handler is defined at the end of the method body. It adopts the concise syntax of C# Switch Expressions.

• Implicit Input: The switch operates on the payload delivered by leave.
• Statement-based: Unlike standard switch expressions which return values, on leave arms execute statements (blocks).
• Must Exit: Every branch in the handler must terminate the method execution (via return or throw). Fall-through or resuming execution of the original block is prohibited.

public IActionResult Process(Data data)
{
    // ... logic ...
    if (bad) leave (400, "Error");
    
    return Ok(); // Standard Exit

    // Handler Section
    on leave 
    {
        // Pattern Matching Syntax
        (400, string msg) => BadRequest(msg),
        
        (int code, _) => StatusCode(code),
        
        ErrorState e => 
        {
            _logger.LogError(e);
            return StatusCode(500);
        }
    }
}

3.3. Semantic Rules & Safety

3.3.1. Scope & Locality

The leave operator works strictly within the bounds of a single method (or lambda/local function). It cannot jump across method boundaries.

3.3.2. Strict Exhaustiveness

The compiler performs static analysis to ensure all types emitted by leave are handled.

• If the code contains leave (int, int), the on leave block must contain a pattern matching (int, int).
• Failure to handle a type results in a Compile-Time Error.

3.3.3. Resource Management (RAII)

The mechanism respects using blocks. When leave is invoked, the runtime guarantees that Dispose() is called for all IDisposable objects in the scopes being exited before the jump to the handler occurs.

using (var file = File.Open(...)) {
    if (empty) leave (0); // file.Dispose() is called here automatically
}

3.4. Tuple Support (Anonymous States)

To reduce boilerplate (avoiding the need to define a struct for every local error), LFH supports ValueTuple.

• Best Practice: Use Tuples for simple, method-local control flow.
• Best Practice: Use Records/Structs for domain-specific errors that might need to be reused or documented.

4. Examples

Scenario A: Replacing goto in Nested Loops

Goal: Exit a nested loop cleanly with context.

public (int r, int c) FindTarget(int[][] matrix, int target)
{
    for (int r = 0; r < matrix.Length; r++)
    {
        for (int c = 0; c < matrix[r].Length; c++)
        {
            if (matrix[r][c] == target) return (r, c); // Found
            if (matrix[r][c] < 0)       leave (r, c);  // Invalid data found
        }
    }
    return (-1, -1);

    on leave 
    {
        (int r, int c) => 
        {
            Console.WriteLine($"Aborted at [{r},{c}] due to negative value.");
            return (-1, -1);
        }
    }
}

Scenario B: Replacing Exceptions for Validation

Goal: Validate input without the performance cost of try-catch.

public record struct ValidationError(string Field);

public void CreateUser(UserDto user)
{
    // "Guard Clause" style
    if (user.Age < 18)        leave new ValidationError(nameof(user.Age));
    if (user.Name is null)    leave (400, "Name missing");

    // The "Happy Path" remains linear and clean
    _repo.Save(user);
    return;

    on leave 
    {
        ValidationError v => 
            throw new RpcException(new Status(StatusCode.InvalidArgument, $"Invalid field: {v.Field}")),

        (int code, string msg) => 
            throw new RpcException(new Status((StatusCode)code, msg))
    }
}

5. Alternatives Considered

5.1. Block-Scoped Handlers

We considered allowing on leave to be attached to any block (e.g., if (...) { ... } on leave { ... }).

• Reason for Rejection: This reintroduces the complexity of try-catch blocks, encourages nesting, and obscures the flow of execution. Restricting handlers to the end of the method enforces a separation of "Logic" vs. "Exit Handling" and encourages smaller methods.

5.2. Resumable Handlers

We considered allowing the handler to resume execution after the leave point.

• Reason for Rejection: This violates the safety guarantees. leave is often used when an invariant is broken. Resuming would lead to indeterminate states. Enforcing an exit (return/throw) ensures deterministic behavior.

6. Implementation Notes (Compiler Lowering)

The C# compiler (Roslyn) would lower this feature roughly as follows:

1. Synthesized Labels: The on leave block is converted into a series of labelled blocks at the end of the method.
2. Goto Instructions: leave X is lowered to a goto Label_X.
3. Spilling: If the payload is a tuple/value, it is spilled to a synthesized local variable before the jump.
4. Finally Blocks: using statements are preserved as try-finally blocks, ensuring the goto triggers the finally (Dispose) logic.

7. Conclusion

Local Fault Handlers elevate "error handling" from a secondary concern to a first-class citizen of the language syntax. By combining the raw speed of goto with the safety of type checking and the conciseness of pattern matching, LFH allows C# developers to write code that is:

1. Linear: The main algorithm is not cluttered with error handling logic.
2. Safe: All exits are statically verified and typed.
3. Fast: Zero allocation and zero runtime overhead (no stack unwinding).

This proposal bridges the gap between low-level systems programming efficiency and high-level application safety.

[CyrusNajmabadi]

Please read the readme in this repo. Do not open requests or language changes here. Language change requests start as discussions at dotnet/csharplang.

[dmitrykolchev]

Sorry, it's my bad :(
Thanks!