Fio

<a id="readme-top"></a>

[![Contributors][contributors-shield]][contributors-url] [![Forks][forks-shield]][forks-url] [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] [![MIT License][license-shield]][license-url] [![NuGet][nuget-shield]][nuget-url]

<br /> <div align="center"> <a href="https://github.com/fio-fsharp/fio"> <img src="assets/images/fio_logo_wide.png" width="auto" height="300" alt="FIO Logo"> </a> <h3 align="center">🪻 A Type-Safe, Purely Functional Effect System for Asynchronous and Concurrent F#</h3> <p align="center"> <!-- An awesome README template to jumpstart your projects! --> <!-- <br /> <a href="https://github.com/fio-fsharp/fio"><strong>Explore the docs »</strong></a> <br /> <br /> --> <a href="https://iyyel.io/projects/fio/">View Project Post</a> &middot; <a href="https://github.com/fio-fsharp/fio/issues/new?labels=bug&template=bug-report---.md">Report Bug</a> &middot; <a href="https://github.com/fio-fsharp/fio/issues/new?labels=enhancement&template=feature-request---.md">Request Feature</a> </p> </div> <details> <summary>Table of Contents</summary> <ol> <li> <a href="#about-fio">About FIO</a> </li> <li> <a href="#getting-started">Getting Started</a> <ul> <li><a href="#usage">Usage</a></li> <ul> <li><a href="#direct-usage">Direct Usage</a></li> <li><a href="#using-fioapp-recommended">Using FIOApp (Recommended)</a></li> <li><a href="#alternative-dsl-only-style">Alternative: DSL-Only Style</a></li> </ul> </ul> </li> <li> <a href="#Benchmarks">Benchmarks</a> <ul> <li><a href="#benchmark-overview">Benchmark Overview</a></li> <li><a href="#running-benchmarks">Running Benchmarks</a></li> <li><a href="#example">Example</a></li> <li><a href="#experimental-flags">Experimental Flags</a></li> </ul> </li> <li> <a href="#performance">Performance</a> <ul> <li><a href="#execution-time">Execution Time</a></li> <li><a href="#scalability">Scalability</a></li> </ul> </li> <li><a href="#roadmap">Roadmap</a></li> <li> <a href="#contributing">Contributing</a> <ul> <li><a href="#quick-start">Quick Start</a></li> <li><a href="#top-contributors">Top Contributors</a></li> </ul> </li> <li><a href="#license">License</a></li> <li><a href="#contact">Contact</a></li> <li><a href="#acknowledgments">Acknowledgments</a></li> </ol> </details>

About FIO

<!-- [![Product Name Screen Shot][product-screenshot]](https://example.com) !-->

FIO is a type-safe, purely functional effect system for F#, designed for building highly concurrent and asynchronous applications. It provides a lightweight DSL for writing composable programs using functional effects.

Inspired by ZIO and Cats Effect, FIO features:

• An IO monad for managing side effects
• Fibers (green threads) for scalable concurrency
• A focus on purity, type safety, and performance

FIO was developed as part of a master’s thesis in Computer Science at DTU.

Read the thesis (some parts may be outdated).

Note: FIO is under active development. Contributions, feedback, and questions are very welcome!
Feel free to report bugs, request features or reach out.

<p align="right">(<a href="#readme-top">back to top</a>)</p> <!-- GETTING STARTED -->

Getting Started

Getting started with FIO is simple:

1. Install .NET
2. Use an editor like VS Code, Visual Studio, or Rider (or even vim)
3. Clone this repository
4. Open it in your editor
5. Explore the FSharp.FIO.Examples project or create your own F# file

Usage

You can use FIO in two ways:

• Directly by creating and running effects manually (examples in FSharp.FIO.Examples)
• Via FIOApp, which simplifies setup and runtime management (examples in FSharp.FIO.Examples.App)

Direct Usage

Create a new F# file and open the DSL, IO and Concurrent runtime modules:

module DirectUsage

open FSharp.FIO.DSL
open FSharp.FIO.Lib.IO
open FSharp.FIO.Runtime.Concurrent

[<EntryPoint>]
let main _ =
    let askForName = fio {
        do! FConsole.PrintLine "Hello! What is your name?"
        let! name = FConsole.ReadLine ()
        do! FConsole.PrintLine $"Hello, %s{name}! Welcome to FIO! 🪻💜"
    }
    
    Runtime().Run askForName
    |> fun fiber -> fiber.Task ()
    |> Async.AwaitTask
    |> Async.RunSynchronously
    |> printfn "%A"
    0

Run it with:

$ dotnet run

And you'll see the following output:

Hello! What is your name?
Daniel
Hello, Daniel, welcome to FIO! 🪻💜
Ok ()

Using FIOApp (Recommended)

Wrap your effect in a FIOApp to simplify boilerplate. Open the App module:

module FIOAppUsage

open FSharp.FIO.DSL
open FSharp.FIO.Lib.IO
open FSharp.FIO.App

type WelcomeApp() =
    inherit FIOApp<unit, exn> ()

    override _.effect = fio {
        do! FConsole.PrintLine "Hello! What is your name?"
        let! name = FConsole.ReadLine ()
        do! FConsole.PrintLine $"Hello, %s{name}! Welcome to FIO! 🪻💜"
    }

WelcomeApp().Run()

Same execution as before:

$ dotnet run

and same output as well:

Hello! What is your name?
Daniel
Hello, Daniel, welcome to FIO! 🪻💜
Ok ()

Alternative: DSL-Only Style

Prefer DSL chaining? Use bind (>>=) directly:

module DSLOnly

open FSharp.FIO.DSL
open FSharp.FIO.Lib.IO

let askForName =
    FConsole.PrintLine "Hello! What is your name?" >>= fun _ ->
    FConsole.ReadLine () >>= fun name ->
    FConsole.PrintLine $"Hello, %s{name}, welcome to FIO! 🪻💜"

Benchmarks

This repository includes five benchmarks, each designed to evaluate a specific aspect of concurrent computation. All benchmarks are adapted from the Savina – An Actor Benchmark Suite.

Benchmark Overview

• Pingpong – Message sending and retrieval between two actors
• Threadring – Message passing with frequent fiber context switching
• Big – Many-to-many message passing with high channel contention
• Bang – Many-to-one messaging, stressing a single receiver
• Fork – Measures fiber spawning overhead

Running Benchmarks

The benchmarks accept a variety of command-line options:

USAGE: FSharp.FIO.Benchmarks [--help]
                             [--direct-runtime]
                             [--cooperative-runtime <ewc> <ews> <bwc>]
                             [--concurrent-runtime <ewc> <ews> <bwc>]
                             [--runs <runs>]
                             [--actor-increment <actorInc> <times>]
                             [--round-increment <roundInc> <times>]
                             [--pingpong <roundCount>]
                             [--threadring <actorCount> <roundCount>]
                             [--big <actorCount> <roundCount>]
                             [--bang <actorCount> <roundCount>]
                             [--fork <actorCount>]
                             [--save <saveToCsv>]
                             [--savepath <absolutePath>]

OPTIONS:

    --direct-runtime      specify Direct runtime
    --cooperative-runtime <ewc> <ews> <bwc>
                          specify Cooperative runtime with ewc, ews and bwc
    --concurrent-runtime <ewc> <ews> <bwc>
                          specify Concurrent runtime with ewc, ews and bwc
    --runs <runs>         specify number of runs for each benchmark
    --actor-increment <actorInc> <times>
                          specify the value of actor increment and the number of times
    --round-increment <roundInc> <times>
                          specify the value of round increment and the number of times
    --pingpong <roundCount>
                          specify number of rounds for Pingpong benchmark
    --threadring <actorCount> <roundCount>
                          specify number of actors and rounds for Threadring benchmark
    --big <actorCount> <roundCount>
                          specify number of actors and rounds for Big benchmark
    --bang <actorCount> <roundCount>
                          specify number of actors and rounds for Bang benchmark
    --fork <actorCount>   specify number of actors for Fork benchmark
    --save <saveToCsv>    should save benchmark results to csv file
    --savepath <absolutePath>
                          specify absolute path to save the benchmark results csv file
    --help                display this list of options.

Example

To run each benchmark 30 times using the concurrent runtime (39 evaluation workers, 200 evaluation steps, 1 blocking worker):

--concurrent-runtime 39 200 1 --runs 30 --pingpong 150000 --threadring 10000 10 --big 250 10 --bang 10000 10 --fork 20000

Experimental Flags

FIO also supports optional compile-time flags:

• DETECT_DEADLOCK – Enables a simple thread that attempts to detect deadlocks during execution

• MONITOR – Starts a monitoring thread that prints internal runtime structure state during execution

Note: These features are experi