[Proposal] Partial Local Functions

[biqas]

1. Abstract

This proposal introduces partial local functions as a new language feature in C#. Similar in spirit to partial methods in partial classes, partial local functions allow a programmer to declare a local function within a method body without immediately providing an implementation. A code generator (or another part of the system) can later supply the implementation in a separate “partial” part.

2. Motivation

Modern software systems often blend handwritten code with automatically generated code. In many scenarios, it is useful to expose extension points within a method without forcing the user to provide all implementation details upfront. Specifically, partial local functions:

• Enhance Separation of Concerns: Users can call a local function whose implementation is provided later (e.g., by a code generator), decoupling the “what” from the “how.”
• Improve Maintainability: Generated code can be updated or regenerated without modifying the user-authored code that calls the partial local function.
• Reduce Boilerplate: Users avoid the need to create full stub methods or resort to more verbose callback patterns.
• Facilitate Domain-Specific Extensions: Code generators—used in areas such as dependency injection, logging, or validation—can complete user-declared partial local functions without modifying the original source file.

3. Design Overview

3.1. Declaration and Implementation

A partial local function is declared inside a method with the partial modifier. There are two parts:

1. User Declaration: The user declares the function’s signature. For non-void functions that might be left unimplemented by a code generator, an optional default return expression may be provided.

2. Generated Implementation: A code generator (or a manually maintained “partial part”) supplies the function body later in the same method.

Example with a Void Return Type:

void ProcessData(Data input)
{
    // Declaration of a partial local function.
    partial void ValidateInput(Data data);

    // Call to the partial local function.
    ValidateInput(input);

    // ... additional code ...
}

Example with a Non-Void Return Type and a Default Value:

void ProcessData(Data input)
{
    // Declaration of a partial local function with a non-void return type.
    // The 'default' clause supplies a fallback return value if no implementation is provided.
    partial int ComputeResult() default => 0;

    int result = ComputeResult();
    // ... additional code that uses result ...
}

In a separate “partial part” (for example, in a generated code region or file), an implementation may be provided:

void ProcessData(Data input)
{
    // This code is generated and merged with the user code at compile time.
    partial int ComputeResult()
    {
        // A more meaningful computation.
        return input.Value * 2;
    }
}

or maybe like this

// This code is generated and merged with the user code at compile time.
partial int ProcessData(Data input).ComputeResult()
{
    // A more meaningful computation.
    return input.Value * 2;
}

If both a default and a generated implementation exist, the generated implementation takes precedence.

3.2. Syntax and Placement

• Modifier: The keyword partial is applied to local function declarations within method bodies.
• Scope: A partial local function is accessible only within its containing method.
• Location Flexibility: The declaration and implementation may appear in different regions or source files (provided they are merged in the same compilation unit). They must be associated with the same logical method scope.
• Default Clause: For non-void partial local functions declared without an immediate implementation, an optional default => clause may be provided to specify the fallback return value. If no default is provided, then an implementation must be supplied by a code generator; otherwise, calls become a compile-time error.

3.3. Semantics and Restrictions

• Return Types:

  • Void Functions: If a void partial local function is declared without an implementation, then, similar to partial methods in classes, calls to it are removed at compile time, incurring no runtime overhead.

• Non-Void Functions: Partial local functions with non-void return types are allowed. For safety, one of the following must hold:

  • An implementation is provided (by the user or a code generator), or
  • A default return expression is specified in the declaration via a default => clause.
    This requirement avoids ambiguity about the value returned when the function is invoked.

• Accessibility: As local functions, partial local functions inherit the containing method’s scope and cannot be declared with additional access modifiers.

• Call Elision and Inlining:

  • When no implementation is provided for a void partial local function, the call is eliminated entirely.
  • For non-void functions with a default clause and no generated implementation, the call may be replaced at compile time with the default expression.
  • In all cases where an implementation is present, the compiler treats the function like any regular local function, allowing optimizations such as inlining.
  • Consistency: If multiple declarations (user and generated) are provided for the same partial local function, their signatures—including return types and parameters—must match exactly. Mismatches result in a compile-time error.

• Error Handling:

  • If a non-void partial local function is declared without a default and no implementation is provided, any call to it results in a compile-time error.
  • Multiple implementations for the same partial local function are not allowed.

4. Performance Considerations

While similar extension points could be achieved using method delegates (or lambda expressions), partial local functions are designed with performance in mind:

• Compile-Time Resolution:
  Partial local functions are resolved and merged at compile time. This eliminates the runtime indirection and overhead typically associated with delegate invocations.

• Inlining and Optimization:
  When an implementation is present (or when a default clause is used), the compiler treats the function like any other local function. It can inline the function or apply other optimizations, ensuring high-performance execution.

• Zero-Overhead Abstraction:
  For void partial local functions, if no implementation is provided, the compiler can remove calls entirely. For non-void functions with a default clause, calls may be replaced with a constant expression. In both cases, the performance penalty common to delegate-based approaches (such as closure allocations or invocation indirection) is avoided.

• Avoiding Closure Allocations:
  Local functions that do not capture local state incur no extra allocations. In contrast, delegates—especially those capturing context—often require heap allocations for closures.

5. Conclusion

The introduction of partial local functions in C# is motivated by the need to seamlessly integrate generated code with handwritten user code at a local scope. Importantly, the design leverages the performance benefits of local functions over delegate-based solutions, ensuring that these extension points incur minimal runtime overhead.

[333fred]

I see a lot of theoretical use cases in your motivation, but very little in actual examples. What's a real-world example of where you would have wanted this?

[biqas]

User Code (MyStateMachine.cs)

In this file, the user implements the state functions as partial methods with custom logic. The user code then calls the generated state machine runner.

public partial class MyStateMachine
{
    // The user code calls the generated state machine runner.
    private bool RunInlineWithStateMachine(Span<Events> inputs)
    {
        // Example of shared state that might be used by the state functions.
        int i;

        // The user provides the implementations for the state functions.
        // These methods must match the signatures declared in the generated code.
        partial void S(StateS.Input value)
        {
            if (value is StateS.Input.Epsilon)
            {
                i = 0;
            }
        }

        partial void A(StateA.Input value)
        {
            if (i > 10)
            {
                // Custom logic when 'i' is greater than 10.
                Console.WriteLine("Value is high in state A.");
            }
            else
            {
                // Alternative logic.
                Console.WriteLine("Value is low in state A.");
            }
        }

        partial void B(StateB.Input value)
        {
            i++;
        }

        partial void C(StateC.Input value)
        {
            // Custom logic for state C.
            Console.WriteLine("Executing state C.");
        }

        return Run(inputs);
    }
}

Generated Code (MyStateMachine.Generated.cs)

This generated file provides the state machine logic and declares the partial methods for the state functions. The generated code processes the events, handles state transitions, and calls the user-implemented state functions.

public partial class MyStateMachine
{
    // --- Generated State Machine Logic ---
    // This function processes a sequence of events, transitions between states,
    // and calls the user-implemented state functions.
    private bool RunInlineWithStateMachine(Span<Events> inputs)
    {
        // --- Generated Partial Declarations for State Functions ---
        // These declarations force the user to provide implementations.
        partial void S(StateS.Input value);
        partial void A(StateA.Input value);
        partial void B(StateB.Input value);
        partial void C(StateC.Input value);

        partial bool Run(Span<Events> inputs, States state = States.StateS, Events @event = Events.Epsilon)
        {
            // Build an event path: prepend the initial event to the input events.
            var path = new Events[inputs.Length + 1];
            path[0] = @event;
            inputs.CopyTo(path.AsSpan(1));

            // Process each event in the path.
            for (int i = 0; i < path.Length; i++)
            {
                var currentEvent = path[i];

                switch (state)
                {
                    case States.StateS:
                        switch (currentEvent)
                        {
                            case Events.Epsilon:
                                S(StateS.Input.Epsilon);
                                break;
                            case Events.EventA:
                                A(StateA.Input.EventA);
                                state = States.StateA;
                                break;
                            default:
                                return false;
                        }
                        break;

                    case States.StateA:
                        switch (currentEvent)
                        {
                            case Events.EventB:
                                B(StateB.Input.EventB);
                                state = States.StateB;
                                break;
                            case Events.EventD:
                                C(StateC.Input.EventD);
                                state = States.StateC;
                                break;
                            default:
                                return false;
                        }
                        break;

                    case States.StateB:
                        switch (currentEvent)
                        {
                            case Events.EventC:
                                S(StateS.Input.EventC);
                                state = States.StateS;
                                break;
                            case Events.Finish:
                                return true;
                            default:
                                return false;
                        }
                        break;

                    case States.StateC:
                        switch (currentEvent)
                        {
                            case Events.Finish:
                                return true;
                            default:
                                return false;
                        }
                        break;

                    default:
                        return false;
                }
            }
            return false;
        }
    }
}

By inlining both the state machine logic and the user-defined state functions, this approach minimizes overhead and enables high-performance throughput. The potential exists for similar inlining of iterators, which could further enhance performance if the use case demands it.

[biqas]

i want to stay in nano seconds 😉. at the moment im doing exactly how you described. i have tested the local function version and it is fast blazingly fast.

[HaloFour]

There's nothing particularly special about local functions that would make them faster than members of a struct. A local function is nothing but a static method that accepts a struct by ref.

[biqas]

Rationale for Partial Local Functions

While local functions compile down to static methods (and thus have similar performance characteristics to struct members), the motivation for introducing partial local functions is not solely about performance. Instead, the key drivers are:

Improved Code Generation:

Partial local functions would allow code generators to inject or modify logic within a method without having to understand the entire semantic context of that method. By declaring a local function as partial, the developer creates a clear placeholder that the generator can later fill in. This modularity simplifies the code generation process.

Enhanced Maintainability and Clarity:

Just as partial methods and partial properties let you split a type’s behavior across multiple files or parts, partial local functions would do the same for method-level logic. This separation of concerns means that the hand-written “core” logic remains uncluttered while generated code is kept separate, making the codebase easier to understand and maintain.

Ease of Reasoning:

Local functions are naturally scoped to the method in which they are declared, which makes it easier for both developers and code generators to reason about their behavior. With partial local functions, you can clearly delineate the user-supplied code from the generated code, reducing complexity and potential errors.

Consistency with Existing Language Features:

C# already supports partial methods and partial properties to help manage large and complex types. Extending the same concept to local functions creates a consistent model across the language, empowering developers to use partiality at every level of their code—be it at the class, property, or method level.

High-Performance Throughput (as a Bonus):

Although performance is not the primary motivation, having all logic inlined within a single method can enable optimizations (such as inlining) that contribute to high-performance throughput. This is a beneficial side effect rather than the core reason for the change.

In Summary

The introduction of partial local functions is aimed at making code generation within methods simpler and more modular. It provides a clear separation between the core logic and the generated parts, easing both the maintenance and the reasoning process—much like partial methods and properties do for class-level code. This approach is valuable not only for potential performance gains but, more importantly, for improved developer productivity and code clarity.

[HaloFour]

IMO it's a lot more difficult to reason about given you have to be able to declare a partial method that has implementation in multiple places.

Your use case can easily be solved using a partial struct with partial methods. I seriously doubt the performance characteristics of said struct would be at all different given that instance members of a struct has the same signature as the static methods emitted for local functions. There'd also be no difference in whether or not the runtime can inline them, for the same reason. This also has the benefit of avoiding lambda capture, as if any of the partial implementations capture any state in a lambda that forces a full promotion to a display class. IMO, the use case as described it extraordinarily niche.

[huoyaoyuan]

the motivation for introducing partial local functions is not solely about performance.

Local function is mostly unrelated to performance, if not against. At the view of code generation, a local function has no difference with a usual function.
The only feature makes it different is capturing, which can only harm performance.

[CyrusNajmabadi]

I'm missing why existing partial methods are not sufficient for your use cases here. Could you expand on that?

[biqas]

Clarification on Partial Local Function Merging

I'm not suggesting that both user code and generator code contain statements that merge to form a single method flow. Instead, the proposal is that the generated part would only implement the bodies of partial local functions declared in the user’s method. No additional statements would be added outside of those local functions.

Possible Syntax Concept

Consider a scenario where the user declares a partial local function inside a method:

public partial class MyClass
{
    public void ProcessData(Span<int> data)
    {
        partial void IncrementCounter();
        
        // Some user logic here
        IncrementCounter();
        // Some more user logic here
    }
}

In a separate file, the generator would provide an implementation for that partial local function, referencing which method (or “target”) it belongs to:

public partial class MyClass
{
    // Hypothetical syntax to indicate that this partial local function
    // is an implementation for `IncrementCounter` in the `ProcessData` method.
    private partial void IncrementCounter() in ProcessData(Span<int> data)
    {
        // Generated code that is placed exactly where the user calls IncrementCounter().
    }
}

Note: The in ProcessData() syntax is purely illustrative—similar to how explicit interface implementations let you specify the target interface. The key idea is that the generated function body “lives” inside ProcessData without merging statements that the user never declared.

[HaloFour]

Given how ridiculously niche this is, I don't see why the language should consider such a massive amount of effort to support it. Yes, a nested partial struct would be nominally additional boilerplate. But the language shouldn't be optimizing for a use case that virtually nobody will use.

[biqas]

I understand the reaction that partial local functions may seem “ridiculously niche.” After all, not every developer will need to interleave generated code directly within a method’s body. However, that perspective overlooks how language features can evolve and broaden their impact over time—especially features aimed at source generators.

When C# first introduced partial classes, many developers considered them a narrow solution. Yet, partial classes have become integral to a wide variety of generated code patterns (e.g., designer files, EF models, auto-generated proxies), vastly reducing boilerplate. Without partial classes, a lot of the tools we take for granted today wouldn’t integrate so neatly with user code.

The same principle applies to partial local functions:

1. Principal Audience: Source Generator Authors
   Their main benefit isn’t for everyday, hand-written logic. Rather, they’re aimed at generator authors who need to insert logic within a method’s flow. This is important for tasks like:

   • Data Mapping (where complex or nested structures need partial code injection)
   • Serialization (inserting specialized read/write logic within existing method structures)
   • Validation (hooking custom validation calls mid-method)
   • Domain-Specific Workflows (such as GraphQL resolvers, specialized state machines, SQL expression trees mapped to raw SQL, and so on)

2. Reducing Boilerplate
   Right now, generator authors have to inject entire methods or resort to rewriting user methods. Over time, that creates unreadable or unmaintainable code. A partial local function approach would keep the user’s method logic clear and let the generator add small, precise bits of code. This is no more niche than partial classes once were—and we know how integral they’ve become to modern C# tooling.

3. Potential Alternatives
   I’m not fixed on any particular syntax. If interceptors could be extended to handle local functions, or if attributes could mark injection points within a method, that might achieve a similar goal. The real need is a more natural, less hacky way to interleave generated code into an existing method’s flow.

Ultimately, some of today’s “niche” needs become tomorrow’s mainstream features—especially as source generators expand in popularity. If you’re open to examples, I’d be happy to illustrate how partial local functions (or an equivalent concept) can drastically simplify generator scenarios in mapping, validation, SQL expression trees, or beyond.

[HaloFour]

Repeating the same things over and over again isn't likely to change anything. You claim that this is substantially better than nested partial types, and I strongly disagree. I think it makes zero sense to allow two partial functions to have bodies of any shape, let alone for this really narrow use case. The repeated walls of text aren't giving me any new information. We're at an impasse and I will leave it at that.

Also, partial types were added after a huge amount of data showing the friction created by having designed code embedded within regions in user code. They were never niche.

[CyrusNajmabadi]

tbh, i'm just not finding teh reasons for using local functions (vs methods) compelling. If you need this, write a normal partial method and indicate what actually gets passed to it. That actually seems to be a better and clearer way of writing this.

Having a partial local function be able to mutate state in another outer function in another part seems incredibly confusing and not something i think i'd want us to support.