Skip to content
/ Eff Public

A library design for programming with effects and handlers in C#

License

Notifications You must be signed in to change notification settings

nessos/Eff

Repository files navigation

Eff

Nuget Build & Tests License GitHub language count GitHub top language

A library for programming with effects and handlers in C#, inspired by the Eff programming language and the implementation of Algebraic Effects in OCaml, Eff Directly in OCaml. Effects are a powerful language feature that can be used to implement dependency injection, exception handling, nondeterministic computation, trace logging and much more.

Introduction

The Eff library takes advantage of the async method extensibility features available since C# 7. At its core, the library defines a task-like type, Eff<TResult>, which can be built using async methods:

using Nessos.Effects;

async Eff HelloWorld()
{
    Console.WriteLine($"Hello, {await Helper()}!");

    async Eff<string> Helper() => "World";
}

Note that unlike Task, Eff types have cold semantics and so running

Eff hello = HelloWorld();

will have no observable side-effect in stdout. An Eff instance has to be run explicitly by passing an effect handler:

using Nessos.Effects.Handlers;

hello.Run(new DefaultEffectHandler()); // "Hello, World!"

So what is the benefit of using a convoluted version of regular async methods?

Programming with Effects

A key concept of the Eff library are abstract effects:

public class CoinToss : Effect<bool>
{
}

Eff methods are capable of consuming abstract effects:

async Eff TossNCoins(int n)
{
    for (int i = 0; i < n; i++)
    {
        bool result = await new CoinToss();
        Console.WriteLine($"Got {(result ? "Heads" : "Tails")}");
    }
}

So how do we run this method now? The answer is we need write an effect handler that interprets the abstract effect:

public class RandomCoinTossHandler : EffectHandler
{
    private readonly Random _random = new Random();

    public override async ValueTask Handle<TResult>(EffectAwaiter<TResult> awaiter)
    {
        switch (awaiter)
        {
            case EffectAwaiter<bool> { Effect: CoinToss _ } awtr:
                awtr.SetResult(_random.NextDouble() < 0.5);
                break;
        }
    }
}

We can then execute the method by passing the handler:

TossNCoins(100).Run(new RandomCoinTossHandler()); // prints random sequence of Heads and Tails

Note that we can reuse the same method using other interpretations of the effect:

public class BiasedCoinTossHandler : EffectHandler
{
    private readonly Random _random = new Random();

    public override async ValueTask Handle<TResult>(EffectAwaiter<TResult> awaiter)
    {
        switch (awaiter)
        {
            case EffectAwaiter<bool> { Effect: CoinToss _ } awtr:
                awtr.SetResult(_random.NextDouble() < 0.01);
                break;
        }
    }
}

TossNCoins(100).Run(new BiasedCoinTossHandler()); // prints sequence of mostly Tails

Please see the samples folder for more examples of Eff applications.

About

A library design for programming with effects and handlers in C#

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages