fsharp.fio
Advanced tools
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:
FIO was developed as part of a master’s thesis in Computer Science at DTU.
Note: FIO is under active development. Contributions, feedback, and questions are welcome. Please report bugs and request features through GitHub Issues, or contact the maintainer at hey@itsdaniel.dk.
FIO is distributed as five NuGet packages:
dotnet add package FSharp.FIO
The core package includes:
dotnet add package FSharp.FIO.Sockets
Provides TCP socket operations with client, server, and connection pooling functionality.
dotnet add package FSharp.FIO.WebSockets
Provides WebSocket client and server functionality with connection pooling.
dotnet add package FSharp.FIO.Http
Provides composable HTTP server functionality built on ASP.NET Core Kestrel, including routes, handlers, and middleware.
dotnet add package FSharp.FIO.PostgreSQL
Provides PostgreSQL database operations built on Npgsql, including connection pooling, query execution, and transactions.
To get started with FIO:
FIO effects are composable values that can be combined using operators, similar to how Result or Option types can be composed in functional programming. These operators enable you to build complex concurrent programs from simple building blocks.
Bind Operator (>>=)
The bind operator chains effects sequentially, giving you access to previous results:
// Using computation expression
let getUserData userId =
fio {
let! user = fetchUser userId
let! orders = fetchOrders user.Id
return (user, orders)
}
// Equivalent using >>= operator
let getUserData userId =
fetchUser userId >>= fun user ->
fetchOrders user.Id >>= fun orders ->
FIO.Succeed (user, orders)
Zip Operators (<*>, >, <)
Combine effects sequentially with different result handling:
// <*> - Combine results into tuple
let combined = fetchUser() <*> fetchSettings()
// Returns: FIO<User * Settings, 'E>
// *> - Run both, keep second result
let compute =
Console.PrintLine "Starting computation..."
*> calculateResult()
// Returns: FIO<CalculationResult, 'E>
// <* - Run both, keep first result
let withLogging =
performAction()
<* Console.PrintLine "Action completed!"
// Returns: FIO<ActionResult, 'E>
Parallel Zip (<&>)
Execute effects concurrently and wait for both to complete:
// Execute two effects in parallel
let fetchUserAndOrders userId =
fetchUser userId <&> fetchOrders userId
<!> fun (user, orders) ->
{ User = user; Orders = orders }
// Both fetches run concurrently
// Multiple parallel API calls
let dashboard =
getProfile() <&> getNotifications() <&> getActivity()
<!> fun ((profile, notifications), activity) ->
{ Profile = profile
Notifications = notifications
Activity = activity }
Parallel Operators (&>, <&, <&&>)
// &> - Run in parallel, keep second result
let warmupThenCompute = warmupCache() &> calculateResult()
// <& - Run in parallel, keep first result
let computeWithBackground = calculateResult() <& logMetrics()
// <&&> - Run in parallel, discard both results
let fireAndForget =
sendEmail() <&&> updateMetrics() <&&> logActivity()
// All run concurrently, returns FIO<unit, 'E>
OrElse Operator (<|>)
Try the first effect, fallback to the second if it fails:
// Simple fallback
let fetchData = fetchFromCache() <|> fetchFromDatabase()
// Chain multiple fallbacks
let robustFetch =
fetchFromPrimary()
<|> fetchFromSecondary()
<|> fetchFromCache()
<|> FIO.Succeed(defaultValue)
Map Operator (<!>)
Transform the success value without affecting errors:
// Transform a single value
let doubled = computeValue() <!> fun x -> x * 2
// Chain transformations
let pipeline =
fetchNumber()
<!> fun n -> n * 2
<!> fun n -> n + 10
<!> fun n -> $"Result: {n}"
Use computation expressions for complex logic with branching, loops, or multiple let bindings:
let processOrders = fio {
let! orders = fetchOrders()
let mutable processed = 0
for order in orders do
if order.Total > 100.0 then
do! applyDiscount order
do! processOrder order
processed <- processed + 1
return processed
}
Use operators for simple pipelines and functional composition:
let pipeline =
fetchData()
<!> validateData
>>= enrichData
>>= saveData
<* Console.PrintLine "Pipeline completed!"
| Operator | Execution | Returns | Use Case |
|---|---|---|---|
>>= | Sequential | Result of function | Chain with access to previous value |
<*> | Sequential | Tuple | Combine two results |
*> | Sequential | Second | Side effect then main result |
<* | Sequential | First | Main result then side effect |
<&> | Parallel | Tuple | Concurrent execution |
&> | Parallel | Second | Concurrent, prefer second |
<& | Parallel | First | Concurrent, prefer first |
<&&> | Parallel | Unit | Fire-and-forget parallel tasks |
<|> | Sequential | First success | Error recovery with fallback |
<!> | N/A | Transformed | Map over success value |
For more examples of operator usage, see FSharp.FIO.Examples.
You can use FIO in two ways:
FIOApp, which simplifies setup and runtime management (examples in FSharp.FIO.Examples.App)Create a new F# file and open the DSL, IO and Concurrent runtime modules:
module DirectUsage
open FSharp.FIO.DSL
open FSharp.FIO.Console
open FSharp.FIO.Runtime.Default
[<EntryPoint>]
let main _ =
let askForName = fio {
do! Console.PrintLine "Hello! What is your name?"
let! name = Console.ReadLine
do! Console.PrintLine $"Hello, {name}! Welcome to FIO! 🪻💜"
}
let fiber = (new DefaultRuntime()).Run askForName
fiber.UnsafePrintResult()
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 ()
FIOApp provides a high-level framework for running FIO effects with lifecycle management, shutdown hooks, and automatic exit codes. It comes in three variants to suit different needs.
FIOApp comes in three variants to suit different needs:
1. SimpleFIOApp
SimpleFIOApp is a type alias for FIOApp<unit, exn>, used when your effect performs actions without returning a meaningful result.
// SimpleFIOApp = FIOApp<unit, exn>
type WelcomeApp() =
inherit SimpleFIOApp()
override _.effect = fio {
do! Console.PrintLine "Hello! What is your name?"
let! name = Console.ReadLine
do! Console.PrintLine $"Hello, {name}! Welcome to FIO! 🪻💜"
}
2. DefaultFIOApp<'R>
DefaultFIOApp<'R> is a type alias for FIOApp<'R, exn>, used when you need to return a specific value but use standard exceptions for errors.
// DefaultFIOApp<'R> = FIOApp<'R, exn>
type RandomNumberApp() =
inherit DefaultFIOApp<int>()
override _.effect = fio {
let! randomNumber = FIO.Attempt(fun () -> Random().Next(1, 100))
do! Console.PrintLine $"Generated: {randomNumber}"
return randomNumber // Returns int
}
3. FIOApp<'R, 'E>
The generic FIOApp<'R, 'E> base class provides full control over both result and error types, enabling type-safe domain-specific error handling.
type AppError =
| ValidationError of string
| NotFound
| DatabaseError of string
type UserLookupApp() =
inherit FIOApp<string, AppError>()
override _.effect = fio {
do! Console.Print "Enter user ID: "
let! userId = Console.ReadLine
if userId = "" then
return! FIO.Fail(ValidationError "User ID cannot be empty")
else
return $"User: {userId}"
}
// Optional: Override exit code mappings
override _.exitCodeError = function
| ValidationError _ -> 2
| NotFound -> 3
| DatabaseError _ -> 4
unit and uses standard exceptions (most CLI apps)For more examples, see FSharp.FIO.Examples.App.
Prefer DSL chaining? Use bind (>>=) directly:
module DSLOnly
open FSharp.FIO.DSL
open FSharp.FIO.Console
open FSharp.FIO.Runtime.Default
let askForName =
Console.PrintLine "Hello! What is your name?" >>= fun _ ->
Console.ReadLine >>= fun name ->
Console.PrintLine $"Hello, {name}! Welcome to FIO! 🪻💜"
[<EntryPoint>]
let main _ =
let fiber = (new DefaultRuntime()).Run askForName
fiber.UnsafePrintResult()
0
FIO provides optional packages for common scenarios:
Build HTTP servers with composable routes and middleware:
open FSharp.FIO.Http
open FSharp.FIO.Http.RoutesOperators
open FSharp.FIO.Http.MiddlewareOperators
// Define handlers
let helloHandler : HttpHandler<exn> =
HttpHandler.text "Hello from FIO!"
let jsonHandler : HttpHandler<exn> =
HttpHandler.okJson {| message = "JSON response" |}
// Compose routes
let routes =
GET "/" helloHandler
++ GET "/json" jsonHandler
// Run server
let config = ServerConfig.defaultConfig // localhost:8080
Server.runServer config routes
For complete examples, see FSharp.FIO.Examples.Http.
Connect to PostgreSQL databases with connection pooling:
open FSharp.FIO.PostgreSQL
// Configure connection pool
let config = {
ConnectionString = "Host=localhost;Database=mydb;Username=user;Password=pass"
MinPoolSize = 5
MaxPoolSize = 20
ConnectionLifetime = 300
CommandTimeout = 30
}
let pool = Pool.create config
// Query with parameters
let getUserById id = fio {
let sql = "SELECT id, name, email FROM users WHERE id = @id"
let parameters = ["id" @= id]
return! Dsl.queryFirstWithParams sql parameters userMapper pool
}
For complete examples, see FSharp.FIO.Examples.PostgreSQL.
TCP socket client and server functionality. See FSharp.FIO.Sockets for documentation.
WebSocket client and server functionality. See FSharp.FIO.WebSockets for documentation.
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.
Pingpong – Message sending and retrieval between two actorsThreadring – Message passing with frequent fiber context switchingBig – Many-to-many message passing with high channel contentionBang – Many-to-one messaging, stressing a single receiverFork – Measures fiber spawning overheadThe 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.
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
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 experimental and may behave unpredictably.
The following plots illustrate the execution time (measured in milliseconds) and scalability of the available runtime systems across benchmarks.
The runtimes differ in how they manage fibers and blocked operations:
The boxplots show the measured execution time for each benchmark with the shown benchmark and runtime configurations.
The lineplots show for each benchmark, how each runtime scales when the amount of fibers increases.
See the open issues for a full list of proposed features (and known issues).
We welcome contributions! To contribute:
enhancement)git checkout -b feature/AmazingFeaturegit commit -m 'Add AmazingFeature'git push origin feature/AmazingFeatureDistributed under the MIT License. See LICENSE.md for more information.
Daniel Larsen (itsdaniel.dk)
Alceste Scalas (people.compute.dtu.dk)
FAQs
Unknown package
We found that fsharp.fio demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
An impersonated golang.org/x/crypto clone exfiltrates passwords, executes a remote shell stager, and delivers a Rekoobe backdoor on Linux.
Security News
npm rolls out a package release cooldown and scalable trusted publishing updates as ecosystem adoption of install safeguards grows.
Security News
AI agents are writing more code than ever, and that's creating new supply chain risks. Feross joins the Risky Business Podcast to break down what that means for open source security.