Performance-effective Fluent API support

[AlexRadch]

Updated: Fluent API support for static methods

The fluent API is one of the most commonly used design patterns in C#. It is elegant, and expressive and makes the code read like prose. Using extensively and ubiquitously in libraries and public APIs.

However, creating a fluent API can require a lot of ceremony and less efficient performance than a non-fluent API.

I suggest adding the fluent modifier to add performance-effective Fluent API support.

The void fluent(this) modifier at method return specification means that the method returns void and the compiler will substitute the specified parameter this after calling the method to call the next method:

// Class with performance effective fluent methods
public class HttpRequestBuilder
{
    public void fluent(this) Method(HttpMethod method);
    {
        _method = method;
        return; // this method returns void,  the compiler will use self to call the next method
    }
    public void fluent(this) Url(string requestUri) {}
    public void fluent(this) Content(HttpContent this.content) {}
    public void fluent(this) JsonContent<T>(T body, Action<JsonSerializerOptions> action = null) {}
    public void fluent(this) Header(string key, string value) {}
    public void fluent(this) Headers(params string[] headers) {}
    public HttpRequestMessage Build() {} // regular method with return type, that stops fluent support
    public void StopBuild() {} // regular void return method, that stops fluent support
    public static HttpRequestBuilder Create() {}
}

// Fluent calls
var message = HttpRequestBuilder.Create()
    .Url("https://example.com")
    .Method(HttpMethod.Post)
    .Headers(
        "Accept", "application/json",
        "Authorization", "Bearer x"
    )
    .JsonContent(
        new { Name = "X", Quantity = 10 },
        opt => opt.PropertyNameCaseInsensitive = true
    )
    .Build();

// Will be compiled to 
HttpRequestMessage message;
{
    var tempBuilder = HttpRequestBuilder.Create();
    tempBuilder.Url("https://example.com");
    tempBuilder.Method(HttpMethod.Post);
    tempBuilder.Headers(
        "Accept", "application/json",
        "Authorization", "Bearer x"
    );
    tempBuilder.JsonContent(
        new { Name = "X", Quantity = 10 },
        opt => opt.PropertyNameCaseInsensitive = true
    );
    message = tempBuilder.Build();

The void fluent(paramName) modifier at method return specification means that the method returns void and the compiler will substitute the specified parameter paramName after calling the method to call the next method.
The void fluent(paramName) modifier at method return specification is also like the this someType paramName modifier in the extension methods but it is used only to chain fluent methods and does not mean that you create an extension method for someType type.

// Static class with performance-effective fluent methods
public static class Guard
{
    public static void fluent(value) IsNotNull<T>(T? value) {}
    public static void fluent(value) IsLenghtRangeRange(string value) {}
    public static void fluent(value) IsAscii(string value) {}

    // This is an extension method for `string` and a fluent method for the `value` parameter.
    public static void fluent(value) FluentExtentionMethod(this string value) {} 
}

// Fluent
var guarded = Guard
    .IsNotNull(input)
    .IsLenghtRangeRange(10, 125)
    .IsAscii();

// Will be compiled to
string guarded;
{
    Guard.IsNotNull(input);
    Guard.IsLenghtRangeRange(input, 10, 125)
    Guard.IsAscii(input);
    guarded = input;
}

// Next call will not be compiled because `IsNotNull`, `IsLenghtRangeRange`, and `IsAscii` are not extension methods
someString.IsNotNull();

// Next calls will be compiled because `FluentExtentionMethod`, is an extension method
someString.FluentExtentionMethod().IsNotNull();

Also, we can add performance-effective fluent methods to struct:

// Struct with performance-effective fluent methods
public struct Struct
{
    public fluent(this) FluentMethod1() {}
    public fluent(this) FluentMethod2() {}
    public fluent(this) FluentMethodN() {}
}

See the motivation part of the #7325 language idea also.

See these discussions #902 #311 #252 #7231 #169 also.

[HaloFour]

How exactly does this proposal address performance? And what benchmark numbers do you have to back up that claim?

[orthoxerox]

What are the fluent methods that are currently used in hot loops? Something that performs network IO, like HttpRequest, won't really benefit from nanoseconds shaved off by not returning this.

[En3Tho]

public void fluent(this) Url(string requestUri) {}

Syntax is wierd. It's a void but not really void and you have to type fluent for some reason just to make compiler think of it as returning ThisType.

Why not just

public this (or self or whatever "ThisType" is called) FluentMethod() { ... }

This is basically what people in those discussions you mentioned ask for. With Roles the same syntax can be reused everywhere. And there is no need to introduce a keyword for a library concept, not a language/compiler one.

I also don't see any performance benefit. If you're going for full perf you most likely will do whatever necessary to make your builder calls inlineable within a method boundary. Any excessive temps will be removed by native compiler anyway.

[AlexRadch]

The method is void because it returns nothing and a compiler should use self for the next fluent call.

[AlexRadch]

Sorry, the main idea is not about performance, I shouldn’t have written about it. The main idea is about the convenient use and writing of one code for both the regular style code and fluent style code.

I will rewrite my proposal.