Note: these tips are not necessarily ordered by usefulness. For that matter, there might or might not be exactly 10 of them :)

¶Tip 1: Use .fsx Files for Interactive Coding

You can use the F# Interactive 2 ways: you can directly type code into FSI, the F# Interactive window, or you can write code in an .fsx file, and select pieces of the code you want to execute. I recommend the second approach, for at least two reasons. First, FSI is a very primitive environment, .fsx files provide a much richer experience (IntelliSense). Then this encourages writing clean scripts you can reuse later.

This is not specific to scripts, but… if you are on Visual Studio, do yourself a service and install the Visual F# Power Tools - you’ll get nice things such as better code highlighting, refactoring, and more.

To execute code interactively, simply type code in an .fsx file, select a block of code, and hit Alt + Enter. The selected code will be evaluated, and the result will show up in the FSI window. In Visual Studio, you can also select code and right-click “Execute in Interactive”, but shortcuts are way faster.

You can also execute a single-line with Alt + '. I rarely use this option, but this can save you time because you don’t need to select the entire line of code.

In case the keyboard shortcuts to send code to FSI do not work anymore (ReSharper used to over-write them in the past), you can reset them in Visual Studio, by going to Tools / Options / Environment / Keyboard. The 2 commands you need to map are EditorContextMenus.CodeWindow.ExecuteInInteractive and EditorContextMenus.CodeWindow.ExecuteLineInInteractive.

You can also use these shortcuts from a regular .fs file, which can be handy if you want to validate that a piece of code is behaving the way you want.

Interactive coding is by far my main usage for scripts - I use it extensively to prototype designs, run dumb tasks, or explore data or libraries. I realized recently that a few of my C# friends use LinqPad for the same purpose.

¶Tip 2: What is it?

While I encourage working primarily from .fsx files, the FSI window is also very helpful. I use it primarily for small verifications. For instance, I might have in my script file code like this:

let add x y =
  x + y

Once I send it for evaluation into FSI, I will see the following show up in FSI:

val add : x:int -> y:int -> int
>

My function add is now in memory, in my FSI session; I can start typing in the FSI window and use it:

> add 1 2;;
val it : int = 3
>

Enter does not trigger execution in FSI. The ;; indicates to FSI “Please execute everything I just typed, up to that point”. This is useful if you want to type multiple lines of code in FSI, and execute them as a block.

it: in our add 1 2 example, the result showed up as it. We simply ran add, but didn’t assign the result to anything. it now contains the result, until we run another expression. If you want to re-use that value, you can assign it in FSI, by doing for instance let x = it;;.′

Once a value is loaded in your FSI session, it will remain there, available to you until you shadow it (in the example above, x will remain available, until I run for instance let x = 42;;). This is extremely convenient: for instance, you can load a data file once let data = File.ReadAllLines path, and keep using data for as long as you want, without having to reload it between code changes.

FSI often shows an abbreviated version of values for large items. For instance, [1..999] will show up as val it : int list = [1; 2; 3; 4; 5; 6; 7; 8; 9; 10; 11; 12; 13; 14; 15; 16; 17; 18; 19; 20; 21; 22; 23; 24; 25; 26; 27; 28; 29; 30; 31; 32; 33; 34; 35; 36; 37; 38; 39; 40; 41; 42; 43; 44; 45; 46; 47; 48; 49; 50; 51; 52; 53; 54; 55; 56; 57; 58; 59; 60; 61; 62; 63; 64; 65; 66; 67; 68; 69; 70; 71; 72; 73; 74; 75; 76; 77; 78; 79; 80; 81; 82; 83; 84; 85; 86; 87; 88; 89; 90; 91; 92; 93; 94; 95; 96; 97; 98; 99; 100; ...] - note the … at the end, which indicate that there is more.

What if you inadvertently started a very long computation, or an infinite loop? In Visual Studio, you can either kill the session entirely, by right-clicking over the FSI window and selecting “Reset Interactive Session” or Ctrl + Alt + R, or cancel the latest evaluation you requested (“Cancel Interactive Evaluation”, or Ctrl + Break.).

¶Tip 3: Run Scripts from the Command Line

Besides interactive scripting, you can also run a script from the command line, by using FSI.exe:

>fsi.exe "C:\myscript.fsx"

FSI.exe is typically located at C:\Program Files (x86)\Microsoft SDKs\F#\4.0\Framework\v4.0. You can also install it separately, see fsharp.org/use section for instructions for various platforms.

You can define different behaviors in your script, depending on whether it is run interactively or from the command line, like this:

#if INTERACTIVE
let msg = "Interactive"
#else
let msg = "Not Interactive"
#endif

printfn "%s" msg

Updated, Sep 19: thanks Matt Klein for pointing the issue.

For more information on FSI from the command line, check the reference page here.

Updated, Feb 20: Ramon Soto Mathiesen points out that Tip 9 also applies to the command line.

¶Tip 4: Use Relative Paths

Sometimes, your script will reference another resource; for instance, you need to read the contents of a .txt file somewhere. You can use absolute path, as in:

File.ReadAllLines @"C:/data/myfile.txt"

Pre-pending a string with @ makes it a verbatim string, and ignore escape sequences, such as \.

Use / rather than \, so that path work both on Windows and Mono.

However, if that resource lives in a location relative to your script, consider using relative path, so that you can move your script folder around without breaking it.

Relative paths can be a bit tricky; for instance, running the following code interactively…

System.Environment.CurrentDirectory

… produces a potentially unexpected result in FSI:

val it : string = "C:\Users\Mathias Brandewinder\AppData\Local\Temp"
>

You can avoid these issues by using built-in constants, which refer respectively to the directory where the script lives, the script file name, and the current line of the script:

__SOURCE_DIRECTORY__
__SOURCE_FILE__
__LINE__

So if your folder structure was along these lines…

root
  /src/script.fsx
  /data/data.txt

… you could refer to the data file data.txt from your script like this:

let path = System.IO.Path.Combine(__SOURCE_DIRECTORY__,"..","data/data.txt")
System.IO.File.ReadAllText path

¶Tip 5: Including Assemblies

By default, FSI loads FSharp.Core and nothing else. If you want to use System.DateTime, you will need to first open System in your script. If you want to use an assembly that is not part of the standard .NET distribution, you will need to reference it first using #r. Imagine for instance that you installed the Nuget package fsharp.data; to use it in your script, you would do something like:

#r @"../packages/FSharp.Data.2.2.5/lib/net40/FSharp.Data.dll"
open FSharp.Data

When you execute open System in interactive, don’t worry if nothing seems to happen: the only result is a new > showing up in FSI.

For assemblies that are part of .NET but not referenced by default, you can use a shorter version:

#r @"System.Xaml"
open System.Xaml

In Visual Studio, you can right-click a reference from Solution Explorer, and send to F# interactive. You can then directly open it, and start using it in FSI.

Updated, Feb 20: Sergey Tihon shared an interesting comment, explaining where Tip 5 can sometimes go wrong. I’d say, try Tip 5 first, but be aware that this might at times not quite work:

@brandewinder don’t load assemblies like in Tip 5 ) https://t.co/Owft1NmPoo

— Sergey Tihon (@sergey_tihon) February 7, 2016

Updated, Feb 20: F# open source contributor Don Syme share a related nice trick:

@jeroldhaas @sergey_tihon @brandewinder Use #I SOURCE_DIRECTORY, it is wondrous, very satisfying. All relative paths then work

— Don Syme (@dsyme) February 7, 2016

¶Tip 6: Use Paket

The Nuget package manager is useful to consume existing packages. However, by default, Nuget stores assemblies in a folder that includes the package version number. This is very impractical for a script. In our example above, if fsharp.data gets an update, our script reference will be broken once we update the Nuget package:

#r @"../packages/FSharp.Data.2.2.5/lib/net40/FSharp.Data.dll"

Fixing the script requires manually editing the version number in the path, which quickly becomes a pain. Paket provides a better experience, because it stores packages without the version number, in this case, under:

#r @"../packages/FSharp.Data/lib/net40/FSharp.Data.dll"

Your scripts will now gracefully handle version number changes.

If you end up consuming numerous packages, you can make your life even easier, by referencing paths where assemblies might be searched for, using #I:

#I @"../packages/
#r @"FSharp.Data/lib/net40/FSharp.Data.dll"

If your primary goal is to “just script”, consider using Atom or VSCode, with the Ionide plugin. You can create and run free-standing F# scripts, with beautiful Paket integration.

¶Tip 7: Include Files

You might want to use the code from an existing file in your script. Suppose that we have a code file Code.fs somewhere, looking like this:

namespace Mathias

module Common =
  let hello name = sprintf "Hello, %s" name

You can use that code from your script, by using the #load directive:

#load "Code.fs"
open Mathias.Common
hello "World"

You might have to close and re-open the script file if you end up changing the contents of the file.

If the file you are attempting to load contains references to other assemblies or files, you might get an error on the #load statement: “One or more errors in loaded files. The namespace or module … is not defined”. Simply reference the missing assemblies above the #load statement, so that your script uses the same dependencies as the file it refers to.

¶Tip 8: Profile your Code with #time

Another handy directive, #time, turns on basic profiling. Once it is executed, for every block of code you send for execution you will see timing and garbage collection information. For instance, running this code…

#time
[| 1 .. 10000000 |] |> Array.map (fun x -> x * x)

… will produce the following in FSI:

--> Timing now on

Real: 00:00:00.887, CPU: 00:00:00.828, GC gen0: 2, gen1: 2, gen2: 2
val it : int [] =
  [|1; 4; 9; 16; 25; 36; 49; // snipped for brevity

We get the wall time and CPU time it took, as well as some information about garbage collection in generations 0, 1 and 2. This would not replace a full-blown profiler, but this is an awfully convenient tool to figure out quickly if there are obvious ways to improve a piece of code.

Note that every time you execute #time, the timer will be switched from on to off, or vice-versa. This is not always convenient; you can also explicitly set it to the desired state, like this:

#time "on"
// everything now is timed
#time "off"

If you are interested in profiling, you should take a look at PrivateEye; check out Greg Young’s talk at NDC Oslo 2015 to get a feel for what it does.

¶Tip 9: Turn 64-bits on

Hat tip to Rick Minerich for that one. I’ll refer you to his blog post to see how to set FSI to 64 bits to handle large datasets.

¶Tip 10: Bonus Material

Did you know that you could…

• debug an F# script? (around 0:12:35 in)
• inspect the objects in your FSI session with FsEye?
• change the FSI font size in Tools/Options/Environment/Fonts and Colors/Show Settings for/F# Interactive?
• add your own pretty-printer to FSI, like this?
• mess with your coworkers’ mental sanity, by executing (* (opening a multiline comment) in FSI? (credit: Tomas)
• simplify loading references with Visual Studio and Power Tools? (credit: Kit Eason, see details in comments section).

And again… if you are not using the Visual F# Power Tools, you are missing out:

“Don’t let your friends try #fsharp without installing @FSPowerTools.” @dsyme at #ndclondon

— Tomas Petricek (@tomaspetricek) January 15, 2016

That’s what I got! I am sure I forgot some - do you have a useful or favorite trick to share?

• 论文链接

主要介绍了JIT的历史和发展过程， 从上世纪六十年代开始， 一直到现在的第四代JIT系统， 大概有三点：

• 介绍了JIT每一代出现的动机和约束条件
• 介绍了对各种JIT技术的分类方式

  1. Invocation
  2. Executability
  3. Concurrency

• 介绍了各个时期JIT技术的实现方式和优缺点

除此之外还介绍了JIT的工具包以及它们在三个不同的方面的支持程度, 分别是

• Binary code generation.
• Cache coherence.
• Execution.

总体来说，这篇论文算是一个概览，可以当成一个JIT相关论文的查询目录了，它把这过程中的所有研究全部以时间线的方式梳理起来，最后总结分类。

心力衰竭的一些不易被察觉但高度相关的检查结果包括有：心动过速、心音异常（奔马律、舒张期杂音或病理性收缩期杂音）、呼吸急促和肝肿大。胸部X光片和心电图（ECG）可能显示非特异性发现。胸片可显示心脏肥大伴肺充血。心电图结果通常是非特异性的。 这篇文章对青少年心力衰竭的罕见和常见原因进行了概述。

• 原始文章

¶其他

端坐呼吸或端坐呼吸是平躺时发生的呼吸短促，导致患者不得不支撑在床上或坐在椅子上睡觉。它通常被视为心力衰竭的晚期表现，是由于液体重新分布到中央循环，导致肺毛细血管压力增加并导致呼吸困难所致。它也见于腹部肥胖或肺部疾病的情况。端坐呼吸与平呼吸相反，平呼吸是指坐或站直时呼吸急促会加重。

I had already decided to use the very elegant [ocaml-ctypes](https://github.com/ocamllabs/ocaml-ctypes) module for the SRT binding so I went with it and created a [ocaml-sys-socket](https://github.com/toots/ocaml-sys-socket) module using it as well. It was a very interesting experience that I would like to describe here!

ocaml-ctypes

The idea behind OCaml ctypes is to create a binding against a C library without having to write C code, or as least as possible. The most straight-forward way of using it is via [libffi](https://github.com/libffi/libffi) , providing access to dynamically-loaded libraries.

The second way of using it is by letting the module generate the basic C stubs required to build and link against a shared library. This is the mode that we’re going to use here. In this mode, the programmer has to describe the C headers of the library they intent to bind to using dedicated OCaml modules, operators and types. From that description, ocaml-ctypes is able to generate the required glue for the binding.

One advantage of using ocaml-ctypes is that the created bindings make as few assumptions as possible about the OCaml C interfacing API. This is pretty nice, in particular since the OCaml compiler is moving pretty quickly these days (which is awesome!) and also if, perhaps one day, support for multi-core is added to the compiler, which will undoubtedly change the C interface API quite a bit.

dune

[dune](https://github.com/ocaml/dune) (formally jbuilder ) is a build system for OCaml projects that has recently raised to much popularity, particularly due to its tight integration with the rest of the OCaml ecosystem, such as [ocamlfind](http://projects.camlcity.org/projects/findlib.html) and [opam](https://opam.ocaml.org/) .

My personal motto in programming in general is that “Simple things should be simple, but complex things should be possible”. dune certainly does not fit into that category but, rather, makes some complex things extremely easy to setup. It’s the kind of tool that will make your life incredibly easier when what you intent to do fits well within their workflow but might not be easy to bend to some very specific niche use. We will see one such case below.

At any rate, it’s been an amazing experience getting to learn how to use dune and the resulting code and build system is remarkably short and elegant, yet very powerful.

socket.h

socket.h is the Unix header that describes the C API to various socket operations, IP version 4 and 6 as well as unix file sockets. There is also a windows API mimicking it, which makes most code using it easily portable to windows.

Most network-based C libraries refer to socket.h to describe the type of socket that can be used with their API so it’s an important entry point for a lot of network operations and one that would be nice to support as generically as possible in OCaml.

The catch, though, is that, most likely for historical reasons¹, the POSIX specifications only partially defines some of the required data structures and types, which makes it possible to write C code using them but does not give enough information to write C bindings without having to use the compiler to parse the actual system-specific headers of the running host.

For instance, here’s how the sockaddr structure is specified:

The <sys/socket.h> header defines the sockaddr structure that includes at least the following members:sa_family_t sa_family address family
char sa_data[] socket address (variable-length data)

Likewise, here’s what is specified about the size of the socklen_t data type:

<sys/socket.h> makes available a type, socklen_t, which is an unsigned opaque integral type of length of at least 32 bits.

Thus, in order to know the exact offset of sa_family inside the sockaddr structure or the actual size of a socklen_t integer, one has to include the OS-specific header, parse its definitions for that specific OS and, only then, is it possible to compute that offset or data size. Let’s see how it’s done in our binding now!

Putting it together

The C binding requires 4 separate passes:

• The [constants](https://github.com/toots/ocaml-sys-socket/tree/master/src/sys-socket/constants) pass, which computes and exports some specific constant and data sizes, computed from the C headers
• The [types](https://github.com/toots/ocaml-sys-socket/tree/master/src/sys-socket/types) pass, which, given the system-specific constants and sizes exported in the previous phase, defines the actual C data structure bindings.
• The [stubs](https://github.com/toots/ocaml-sys-socket/tree/master/src/sys-socket/stubs) pass, where we define the actual bindings to the C functions that we wish to export in our API.
• Finally, the last pass does a cleanup of the stubs pass to export a relevant and OCaml- (and ocaml-ctypes) specific public API that is to be used by users of the module.

dune makes each of these steps fairly easy to integrate into the next one, defining compilation elements and binaries to build before moving to the next pass.

¶Constants pass

During that pass, we compute and export all required C values defined in the headers. We also add our own constants, which give us the sizes that the POSIX specifications leave up to the OS. Here’s the OCaml code for it:

module Def (S : Cstubs.Types.TYPE) = struct
  let af_inet = S.constant "AF_INET" S.int
  let af_inet6 = S.constant "AF_INET6" S.int
  let af_unix = S.constant "AF_UNIX" S.int
  let af_unspec = S.constant "AF_UNSPEC" S.int
  let sa_data_len = S.constant "SA_DATA_LEN" S.int
  let sa_family_len = S.constant "SA_FAMILY_LEN" S.int
  let sock_dgram = S.constant "SOCK_DGRAM" S.int
  let sock_stream = S.constant "SOCK_STREAM" S.int
  let sock_seqpacket = S.constant "SOCK_STREAM" S.int
  let socklen_t_len = S.constant "SOCKLEN_T_LEN" S.int
  let ni_maxserv = S.constant "NI_MAXSERV" S.int
  let ni_maxhost = S.constant "NI_MAXHOST" S.int
  let ni_numerichost = S.constant "NI_NUMERICHOST" S.int
  let ni_numericserv = S.constant "NI_NUMERICSERV" S.int
end

Pretty straightforward! Some of these constants are defined by the POSIX headers and some are custom defined for our needs, for instance SOCKLEN_T_LEN . Here’s how they are extracted, using the dune build configuration for [gen_constants_c](https://github.com/toots/ocaml-sys-socket/blob/master/src/sys-socket/generator/gen_constants_c.ml):

let c_headers = "
#ifdef _WIN32
  #include <winsock2.h>
  #include <ws2tcpip.h>
#else
  #include <sys/socket.h>
  #include <sys/un.h>
  #include <netdb.h>
#endif
#define SA_DATA_LEN (sizeof(((struct sockaddr*)0)->sa_data))
#define SA_FAMILY_LEN (sizeof(((struct sockaddr*)0)->sa_family))
#define SOCKLEN_T_LEN (sizeof(socklen_t))
#ifndef NI_MAXHOST
  #define NI_MAXHOST 1025
#endif
#ifndef NI_MAXSERV
  #define NI_MAXSERV 32
#endif
"
let () =
  let fname = Sys.argv.(1) in
  let oc = open_out_bin fname in
  let format =
    Format.formatter_of_out_channel oc
  in
  Format.fprintf format "%s@\n" c_headers;
  Cstubs.Types.write_c format (module Sys_socket_constants.Def);
  Format.pp_print_flush format ();
  close_out oc

This OCaml code makes use of ocaml-ctypes to build a binary that exports the OCaml interface defined by Sys_socket_constants.Def . Once compiled, its output looks like this:

include Ctypes
let lift x = x
open Ctypes_static

let rec field : type t a. t typ -> string -> a typ -> (a, t) field =
  fun s fname ftype -> match s, fname with
  | View { ty }, _ ->
    let { ftype; foffset; fname } = field ty fname ftype in
    { ftype; foffset; fname }
  | _ -> failwith ("Unexpected field "^ fname)

let rec seal : type a. a typ -> unit = function
  | Struct { tag; spec = Complete _ } ->
    raise (ModifyingSealedType tag)
  | Union { utag; uspec = Some _ } ->
    raise (ModifyingSealedType utag)
  | View { ty } -> seal ty
  | _ ->
    raise (Unsupported "Sealing a non-structured type")

type 'a const = 'a
let constant (type t) name (t : t typ) : t = match t, name with
  | Ctypes_static.Primitive Cstubs_internals.Int, "NI_NUMERICSERV" ->
    8
  | Ctypes_static.Primitive Cstubs_internals.Int, "NI_NUMERICHOST" ->
    2
  | Ctypes_static.Primitive Cstubs_internals.Int, "NI_MAXHOST" ->
    1025
  | Ctypes_static.Primitive Cstubs_internals.Int, "NI_MAXSERV" ->
    32
  | Ctypes_static.Primitive Cstubs_internals.Int, "SOCKLEN_T_LEN" ->
    4
  | Ctypes_static.Primitive Cstubs_internals.Int, "SOCK_STREAM" ->
    1
  | Ctypes_static.Primitive Cstubs_internals.Int, "SOCK_STREAM" ->
    1
  | Ctypes_static.Primitive Cstubs_internals.Int, "SOCK_DGRAM" ->
    2
  | Ctypes_static.Primitive Cstubs_internals.Int, "SA_FAMILY_LEN" ->
    1
  | Ctypes_static.Primitive Cstubs_internals.Int, "SA_DATA_LEN" ->
    14
  | Ctypes_static.Primitive Cstubs_internals.Int, "AF_UNSPEC" ->
    0
  | Ctypes_static.Primitive Cstubs_internals.Int, "AF_UNIX" ->
    1
  | Ctypes_static.Primitive Cstubs_internals.Int, "AF_INET6" ->
    30
  | Ctypes_static.Primitive Cstubs_internals.Int, "AF_INET" ->
    2
  | _, s -> failwith ("unmatched constant: "^ s)

let enum (type a) name ?typedef ?unexpected (alist : (a * int64) list) =
  match name with
  | s ->
    failwith ("unmatched enum: "^ s)

The files used to describe how to build this binary using dune are located in a separate [generator](https://github.com/toots/ocaml-sys-socket/tree/master/src/sys-socket/generator) directory. Here’s the entry to build this one:

(executable
 (name gen_constants_c)
 (modules gen_constants_c)
 (libraries sys-socket.constants ctypes.stubs))

(rule
 (targets gen_constants.c)
 (deps    (:gen ./gen_constants_c.exe))
 (action  (run %{gen} %{targets})))

(rule
 (targets gen_constants_c)
 (deps    (:c_code ./gen_constants.c))
 (action  (run %{ocaml-config:c_compiler} -I %{lib:ctypes:} -I %{ocaml-config:standard_library} -o %{targets} %{c_code})))

This executable is compiled during the next phase. Let’s move into it now!

¶Types pass

During that phase, we use the constants exported during the previous phase to describe the various C structures and types. This is by far the most complex part of the code, making use of first-class modules and several OCaml tricks.

First, let’s look at how we tell dune that we need to generate the .ml file exporting our required constants from the previous pass:

(rule
 (targets sys_socket_generated_constants.ml)
 (deps    (:exec ../generator/exec.sh)
          (:gen ../generator/gen_constants_c))
 (action  (with-stdout-to %{targets}
            (system "%{exec} %{ocaml-config:system} %{gen}"))))

With only this information, if the code refers to a Sys_socket_generated_constants module, dune will know that this module needs to be generated and how to do it. We will explain later the use of the exec.sh wrapper here.

Now that we can make use of the exported constants in our OCaml code, let’s see how we define the Socklen module, exporting abstract types and interface to use socklen_t integers:

module Constants = Sys_socket_constants.Def(Sys_socket_generated_constants)

module type Socklen = functor (S : Cstubs.Types.TYPE) -> sig
  type socklen
  val socklen_t : socklen S.typ
  val int_of_socklen : socklen -> int
  val socklen_of_int : int -> socklen
end

let socklen : (module Socklen)  =
    match Constants.socklen_t_len with
      | 4 -> (module functor (S : Cstubs.Types.TYPE) -> struct
                 type socklen = Unsigned.uint32
                 let socklen_t = S.uint32_t
                 let int_of_socklen = Unsigned.UInt32.to_int
                 let socklen_of_int = Unsigned.UInt32.of_int
               end)
      | 8 -> (module functor (S : Cstubs.Types.TYPE) -> struct
                 type socklen = Unsigned.uint64
                 let socklen_t = S.uint64_t
                 let int_of_socklen = Unsigned.UInt64.to_int
                 let socklen_of_int = Unsigned.UInt64.of_int
               end)
      | _ -> assert false

module Socklen = (val socklen : Socklen)

As you can see, we make use of first-order modules and the size of the socklen_t integer to define the right API for the compiling host. Now let’s see how we define the sockaddr interface:

module type SaFamily = sig
  type sa_family
  val int_of_sa_family : sa_family -> int
  val sa_family_of_int : int -> sa_family
  
  module T : functor (S : Cstubs.Types.TYPE) -> sig
    val t : sa_family S.typ
  end
end

let saFamily : (module SaFamily)  =
    match Constants.sa_family_len with
      | 1 ->  (module struct
                 type sa_family = Unsigned.uint8
                 let int_of_sa_family = Unsigned.UInt8.to_int
                 let sa_family_of_int = Unsigned.UInt8.of_int                 
                 module T (S : Cstubs.Types.TYPE) = struct
                   let t = S.uint8_t
                 end
               end)
...

module SaFamily = (val saFamily : SaFamily)

module Def (S : Cstubs.Types.TYPE) = struct
  include Constants

  include Socklen(S)

  include SaFamily

  module SaFamilyT = SaFamily.T(S)

  let sa_family_t = S.typedef SaFamilyT.t "sa_family_t"

  module Sockaddr = struct
    type t = unit
    let t = S.structure "sockaddr"
    let sa_family = S.field t "sa_family" sa_family_t
    let sa_data = S.field t "sa_data" (S.array sa_data_len S.char)
    let () = S.seal t
  end
  
  ...
end

Here, too, we make use of the size of sa_family as exported previously to define the right structure fields.

Next step, we need to compile this interface again to export the right offset for the various structures that have been defined. That’s dune’s job again!

First, the generator code:

let c_headers = "
#ifdef _WIN32
  #include <winsock2.h>
  #include <ws2tcpip.h>
#else
  #include <sys/socket.h>
  #include <sys/un.h>
  #include <netinet/in.h>
  #include <netdb.h>
#endif
"

let () =
  let fname = Sys.argv.(1) in
  let oc = open_out_bin fname in
  let format =
    Format.formatter_of_out_channel oc
  in
  Format.fprintf format "%s@\n" c_headers;
  Cstubs.Types.write_c format (module Sys_socket_types.Def);
  Format.pp_print_flush format ();
  close_out oc

And the build instructions:

(executable
 (name gen_types_c)
 (modules gen_types_c)
 (libraries sys-socket.types ctypes.stubs))

(rule
 (targets gen_types.c)
 (deps    (:gen ./gen_types_c.exe))
 (action  (run %{gen} %{targets})))

(rule
 (targets gen_types_c)
 (deps    (:c_code ./gen_types.c))
 (action  (run %{ocaml-config:c_compiler} -I %{lib:ctypes:} -I %{ocaml-config:standard_library} -o %{targets} %{c_code})))

Once, compiled, the exported .ml looks like this:

include Ctypes
let lift x = x
open Ctypes_static

let rec field : type t a. t typ -> string -> a typ -> (a, t) field =
  fun s fname ftype -> match s, fname with
...
  | Struct ({ tag = "sockaddr"} as s'), "sa_data" ->
    let f = {ftype; fname; foffset = 2} in
    (s'.fields <- BoxedField f :: s'.fields; f)
  | Struct ({ tag = "sockaddr"} as s'), "sa_family" ->
    let f = {ftype; fname; foffset = 1} in
    (s'.fields <- BoxedField f :: s'.fields; f)
  | View { ty }, _ ->
    let { ftype; foffset; fname } = field ty fname ftype in
    { ftype; foffset; fname }
  | _ -> failwith ("Unexpected field "^ fname)

let rec seal : type a. a typ -> unit = function
...
  | Struct ({ tag = "sockaddr_storage"; spec = Incomplete _ } as s') ->
    s'.spec <- Complete { size = 128; align = 8 }
  | Struct ({ tag = "sockaddr"; spec = Incomplete _ } as s') ->
    s'.spec <- Complete { size = 16; align = 1 }
  | Struct { tag; spec = Complete _ } ->
    raise (ModifyingSealedType tag)
  | Union { utag; uspec = Some _ } ->
    raise (ModifyingSealedType utag)
  | View { ty } -> seal ty
  | _ ->
    raise (Unsupported "Sealing a non-structured type")

type 'a const = 'a
let constant (type t) name (t : t typ) : t = match t, name with
  | _, s -> failwith ("unmatched constant: "^ s)

let enum (type a) name ?typedef ?unexpected (alist : (a * int64) list) =
  match name with
  | s ->
    failwith ("unmatched enum: "^ s)

As you can see, this exports all the offsets required to access the fields inside a sockaddr_t structure. We’re now ready to move to the final stage, which is the actual binding stubs!

¶Binding stubs

First step in this pass, just like with the previous ones, we need to configure dune to be able to build the exported .ml code from the types pass:

(rule
 (targets sys_socket_generated_types.ml)
 (deps    (:exec ../generator/exec.sh)
          (:gen ../generator/gen_types_c))
 (action  (with-stdout-to %{targets}
            (system "%{exec} %{ocaml-config:system} %{gen}"))))

And we can now define the proper bindings. Here’s how it looks like:

open Ctypes

module Def (F : Cstubs.FOREIGN) = struct
  open F

  module Types = Sys_socket_types.Def(Sys_socket_generated_types)

  open Types

  let getnameinfo = foreign "getnameinfo" (ptr sockaddr_t @-> socklen_t @-> ptr char @-> socklen_t @-> ptr char @-> socklen_t @-> int @-> (returning int))

...
end

As you can see, we’re exporting the getnameinfo function, taking various arguments, including a pointer to a sockaddr_t structure and a couple of socklen_t integers, making use of all the various data types and structures previously defined. The exact specifications of this function can be found here. We can now define out top-level API…

¶Final API

Building upon the previous modules, we export various OCaml idiomatic APIs that the binding user can now use to build new bindings against the socket.h APIs.

Just like with the previous steps, first we need to configure the build system:

(rule
 (targets sys_socket_generated_stubs.ml)
 (deps    (:gen ./generator/gen_stubs.exe))
 (action  (run %{gen} ml %{targets})))

(rule
 (targets sys_socket_generated_stubs.c)
 (deps    (:gen ./generator/gen_stubs.exe))
 (action  (run %{gen} c %{targets})))

This time, we need ocaml-ctypes to generate two compilation units: a .ml file describing the API exported during the stubs phase, as well as the C code to glue it with the C APIs. Here’s the code for that generator:

let c_headers = "
#ifdef _WIN32
  #include <winsock2.h>
  #include <ws2tcpip.h>
#else
  #include <sys/socket.h>
  #include <netinet/in.h>
  #include <arpa/inet.h>
  #include <netdb.h>
#endif
#include <string.h>
"

let () =
  let mode = Sys.argv.(1) in
  let fname = Sys.argv.(2) in
  let oc = open_out_bin fname in
  let format =
    Format.formatter_of_out_channel oc
  in
  let fn =
    match mode with
      | "ml" -> Cstubs.write_ml
      | "c"  ->
         Format.fprintf format "%s@\n" c_headers;
         Cstubs.write_c
      | _    -> assert false
  in
  fn ~concurrency:Cstubs.unlocked format ~prefix:"sys_socket" (module Sys_socket_stubs.Def);
  Format.pp_print_flush format ();
  close_out oc

The exported .ml and .c files are omitted here for simplicity but the reader can generated them themselves from the [ocaml-sys-socket](https://github.com/toots/ocaml-sys-socket) repository if they are curious about their actual content.

We can now export our top-level API:

open Ctypes

include Sys_socket_types.SaFamily

include Sys_socket_stubs.Def(Sys_socket_generated_stubs)

type socklen = Types.socklen
let socklen_t = Types.socklen_t
let int_of_socklen = Types.int_of_socklen
let socklen_of_int = Types.socklen_of_int

module Sockaddr = struct
  include Types.Sockaddr
  let from_sockaddr_storage = from_sockaddr_storage t
  let sa_data_len = Types.sa_data_len
end

let getnameinfo sockaddr_ptr =
  let maxhost = Types.ni_maxhost in
  let s = allocate_n char ~count:maxhost in
  let maxserv = Types.ni_maxserv in
  let p = allocate_n char ~count:maxserv in
  match getnameinfo sockaddr_ptr (socklen_of_int (sizeof sockaddr_t))
                    s (socklen_of_int maxhost) 
                    p (socklen_of_int maxserv)
                    (Types.ni_numerichost lor
                     Types.ni_numericserv)  with
    | 0 ->
      let host =
        let length =
          Unsigned.Size_t.to_int
            (strnlen s (Unsigned.Size_t.of_int maxhost))
        in
        string_from_ptr s ~length
      in
      let port =
        let length =
          Unsigned.Size_t.to_int
            (strnlen p (Unsigned.Size_t.of_int maxserv))
        in
        let port =
          string_from_ptr p ~length
        in
        try
          int_of_string port
        with _ ->
          match getservbyname p null with
            | ptr when is_null ptr -> failwith "getnameinfo"
            | ptr ->
               Unsigned.UInt16.to_int
                 (ntohs (!@ (ptr |-> Types.Servent.s_port)))
      in
      host, port
    | _ -> failwith "getnameinfo"

...

open Ctypes

(** Ctypes routines for C type socklen_t. *)
type socklen
val socklen_t : socklen typ
val int_of_socklen : socklen -> int
val socklen_of_int : int -> socklen

(** Generic sockaddr_t structure. *)
module Sockaddr : sig
  type t
  val t : t structure typ
  val sa_family : (sa_family, t structure) field
  val sa_data : (char carray, t structure) field
  val sa_data_len  : int

  val from_sockaddr_storage : SockaddrStorage.t structure ptr -> t structure ptr
end

(** IP address conversion functions. *)
val getnameinfo : sockaddr ptr -> string * int

...

That’s it! We now have ocaml-ctypes specific data types and structures that can be used to interface with the host’s native socket.h APIs. Note that we also worked on top of the original low-level binding to getnameinfo to export a higher-level function more idiomatic to the OCaml language.

Lagniappe: cross-compilation to Windows

On windows platforms, liquidsoap is compiled using [ocaml-cross-windows](https://github.com/ocaml-cross/opam-cross-windows) and, since windows does have compatible socket APIs, we wanted to also look at cross-compiling for the windows target, which is where we hit a snag on the current dune support.

The problem is that, at each intermediary steps, in the case of a cross-compilation, the compiled binaries need to use the target’s OS headers and not the host’s headers, otherwise we end up using offsets specific to e.g. Debian but for a windows binary.

In this case, this means that the compiled .exe binaries need to be windows binaries and that we need to execute them as windows native binaries, using [wine](https://www.winehq.org/) .

dune has a truly amazing support for cross-compiling, which we do not cover here, but, unfortunately, its primitives for building and executing binaries do not yet cover this use case. Thus we had to trick it into compiling things the way we wanted to do, which why we are using the exec.sh wrapper. Here’s its code:

#!/bin/sh

SYSTEM=$1
CMD=$2
ARG=$3

if test "${SYSTEM}" = "mingw"; then
  wine $CMD $ARG
elif test "${SYSTEM}" = "mingw64"; then
  wine64 $CMD $ARG
else
  $CMD $ARG

Now, you can go back to the previous dune files and see how this wrapper allows to execute binaries according to the system that the corresponding ocamlopt compiler has been configured to build for.

Conclusion

It’s been a fun time working on this binding! It’s amazing to see the level of details that can be built through ocaml-ctypes using their provided primitives. Ultimately, the binding is very clean and elegant, with very few low-level assumptions.

Likewise, the simplicity and power of the dune build system makes this very fluid to build. Without it, each of the described steps above would have been much more painful to execute and compile.

[1]: My bet is that, at the time the POSIX specifications were being written, there we already several inconsistent socket.h headers out in the wild among the various historical UNIX flavors…

The general idea is simple - we want a fine-grained concurrency primitive, that will let us easily compose chain of operations in sequential manner. Of course we could use threads here, but the question is: are threads fine-grained? In many managed languages with OS threads exposed, they can be quite heavy eg. by default in .NET each thread takes around 1MB of memory and requires calling kernel code to cooperate with other threads, which is an expensive operation on its own.

What we’re after, are more lightweight structures (less than 1kB), that can live fully in a user space, so that we can have even millions of them cooperating frequently with each other without heavy performance penalties.

Before we begin, I think it’s good to discuss different designs. We’ll cover several different topics to be able to make more informed decisions, that we’re up to apply to our own solution.

¶Preemptive vs cooperative scheduler

Scheduler is a subsystem, which direct responsibility is to assign CPU core processing power to a particular fiber. It’s also responsible for coordinating fibers execution. The two most common categories of schedulers are preemptive and cooperative.

A preemptive scheduler is the one, that’s always in control of fiber execution. It’s able to decide on its own, when fiber can be started and stopped. The most obvious example of such is a thread scheduler existing on most operating systems.

Preemptive scheduler usually works in one of two ways:

• Time based scheduler takes a quant of CPU time and gives it to a given fiber, which ten can execute its logic until it reaches its execution time limit (of course, it can finish earlier). This is how OS thread scheduler, but also how Go goroutine scheduler works.
• Another variant is step-based scheduler, which splits fiber’s function body into series of (more or less equal) steps. Then each fiber is given a number of steps to execute before preemption occurs. Example of such is Erlang’s BEAM - it simply allows each process to execute up to 2000 “reductions”, where each reduction is basically a function call. And since in Erlang there are no loops, only tail-recursive functions, this approach works well for long-living iterative processes as well.

One of the problems with preemptive schedulers is that they usually need some kind of involvement from the compiler or hosting virtual machine in order to work. For this reason, most of the fiber libraries use cooperative schedulers to perform their work.

A cooperative scheduler doesn’t have a concept of preemption - once started by the scheduler, a fiber will execute until it doesn’t give back the control willingly. This is often done with dedicated programming constructs, and often is known as yielding, parking or awaiting.

In cooperative variant, a fiber body is usually split into series of discrete steps, between which fiber gives control back to the scheduler.

Keep in mind that these two are not mutually exclusive - a preemptive scheduler often provides a way for a fiber to return control back to it when it’s known that fiber won’t be executing any longer eg. because it has been put to sleep for a while.

¶Stackless vs. stackful

A concept, that’s somewhat related to a topic above is the idea of stackless and stackful coroutines.

A stackful variant is aware of underlying execution stack and can preserve/restore parts of it when yielding/continuing a fiber. Examples of this approach could be Go, Lua, Python asyncio and in the future, also Java Loom project. Implementing such option (if it’s not implemented by a runtime already) usually requires diving deep into low-level internals, since execution stack is not something that most managed languages offers the users to play with, and doing so without coordination with runtime can cause problems - like determining liveness of objects for GC purposes.

Stackless coroutine usually captures locals that we want to preserve as part of callback object (lambda), that is allocated as an object on the heap and scheduled on yield continuation. These steps are usually visible directly in code (eg. await in C#, Rust and JavaScript, but also joints of Scala for-comprehensions, bang-suffix in F# or Haskell do-notation), but sometimes can be implicit like in case of Kotlin. Take into account that while many languages offer syntax support for those constructs, it’s not explicitly necessary to work - take a look at JavaScript and Promise.then as an example.

Stackless coroutines usually construct their logic around one of two concepts:

1. Finite state machines - this variant is usually faster and can be encoded manually (example of such case is Akka actors), but for a human eye it usually doesn’t really read as a sequential step-by-step program execution, unless it has some support from the compiler itself (see: C# and Rust).
2. Monadic sequencing via bind/flatMap operator, which is very popular in functional languages. While we cover it in more details in the rest of this blog post, for now it’s enough to say that it’s a way to chain callback-based behaviors together in a way, that resembles standard sequential code.

For sure one of the advantages of stackful coroutines is that they’re mono-colored: you can yield/continue coroutine execution from within any other function, while in the stackless variant splits your world into two-colored functions - synchronous and asynchronous - where async one can be only called and yielded safely (without blocking underlying OS thread) from within another async function.

¶Eager vs lazy fibers

We already mentioned two important events in fiber execution life cycle - starting and parking. Here I briefly discuss about different design decisions on when to start a fiber execution.

Eager execution means, that fiber is started automatically after its creation. An example of such are Scala Future[A] and JavaScript Promise. Since execution process starts right away, we’re willingly resign from a certain degree of control over how or when to execute given fiber. Usually this is solved by wrapping a fiber creation into another function or lambda.

Lazy execution is much more common and preferred way of work, as it allows us to separate place where we want to define our asynchronous sequence of steps from the place, where the execution details are defined. It’s used in C# TPL as well as pretty much in all functional languages implementations (excluding Scala futures mentioned earlier).

¶Interruption

There are also few decisions regarding premature escaping the fiber execution, also known as interruption/cancelation: one of them requires passing special object - a token - between method calls and explicit checking for its completion. It is how C# Tasks work. However putting such requirement onto the API user can be cumbersome and error-prone option. Therefore pretty much every other coroutine library either allows to direcly interrupt a fiber or (like in case of F# Async) passes cancelation tokens and check if they were triggered under the hood.

¶Implementation

Since we talked a bit about various approaches, let’s get to the meat of this blog post: implementing our own coroutine library in F#. So, what properties will it have?:

1. We use cooperative scheduling (we don’t want to tweak the compiler) of stackless fibers with support from F# computation expression for nice syntax.
2. We use simple approach by defining custom bind operator with support from F# computation expressions. No state machines.
3. We’ll use lazy invocation.
4. We’ll make use of implicitly passed cancelation tokens. We’ll handle them directly inside the linking code.

All of these give us in very similar approach to that found inside of native F# Async data type. To begin with, we’ll simply define the shape of our fiber.

Underneath, pretty much every cooperative stackless coroutine approach uses callbacks to drive the flow of synchronous segments of code to be executed one after another. So what we need is a callback which takes a result of previous coroutine and schedules in within some context of execution:

type Fiber<'a> = Fiber of (ExecutionContext -> FiberCallback<'a> -> unit)

Here we’ll represent Fiber as a simple single-case discriminated union. We could as well define other specialized cases, like:

• Situation when coroutine is executed immediately and doesn’t need to be awaited on: think about variant of ValueTask from C# Task Parallel Library.
• Case when coroutine fails - in that case we might want to store an artificial tracing context that would allow us to create nicely-formatted “stack traces”: since .NET Core 2.1, C# already provides similar solution however AFAIK it’s been solved differently.

Ok, but what are ExecutionContext and FiberCallback<'a>? Let’s start from callback. We can represent it as follows:

type FiberCallback<'a> = FiberResult<'a> -> unit

It’s just a simple function, which takes result of previous fiber execution and handles it. What’s the FiberResult<'a> then?

Our fiber can complete successfully (returning a value) or fail with an exception. We’ll be conservative here and won’t go into more typed world of IO bifunctor. We can easy define these possible outputs in F# using Result<'a, exn>.

Question is: is that exhaustive? Well… no. As we already mentioned, there’s a 3rd state, often overlooked or conflated with failure: a canceled fiber. A canceled fiber doesn’t produce any output - since it was canceled before completion. In F# we already know how to represent an absence of value - simply use an option. Therefore our ultimate Fiber result type could look like this:

type FiberResult<'a> = Result<'a, exn> option

Now, the ExecutionContext. While it can be compound of many different capabilities throughout the system - even to serve as functional equivalent of dependency injection - here I’ll use it only for implicit passing of specific scheduler info and cancelation tokens from one fiber to another.

type ExecutionContext = IScheduler * Cancel

IScheduler interface is used to abstract component responsible for running our fibers. At the moment all we need is an ability to schedule fiber execution:

[<Interface>]
type IScheduler = 
  abstract Schedule: (unit -> unit) -> unit

While the name and signature imply multithreaded execution model, it doesn’t have to be the case. We can even implement scheduler which will simulate everything on a single core.

For now, we can simply implement a scheduler API on top of our standard .NET thread pool:

module Scheduler

open System.Threading

let shared = 
  { new ISchedule with
      member __.Schedule fn = 
        ThreadPool.QueueUserWorkItem(WaitCallback (fun _ -> fn())) |> ignore  }

¶Cancellation

Now it’s a time for cancellation tokens. Of course we could just make use of a flag - conceptually working like native .NET CancellationToken. However given implicit cancellation, it may not be enough. Example:

Imagine, that inside our fiber we’re scheduling the race between two other fibers ie. one writing data to a file and other which will complete after timeout. Now, whenever one of them completes first, we want to cancel another one to stop wasting resources for result that no longer matters.

This simple scenario is similar to what .NET Task.WhenAny is used - with a difference that, unlike TPL, we want to actually cancel other executing tasks instead of letting them run (potentially forever) :D

Now, since our cancellation is not explicit, we need to deal with few things:

1. Whenever parent fiber is cancelled, all child fibers it spawned are also cancelled.
2. Whenever we cancel a fiber that loose the race, we don’t want to accidentally cancel a token of its parent.

This behavior implies at least using two separate tokens, however in practice it will be more pragmatic to make our Cancel token work as a tree hierarchy - this way we can easily keep track of things and support more complex scenarios.

[<Sealed;AllowNullLiteral>]
type Cancel(parent: Cancel) =
  let mutable flag: int = 0
  let mutable children: Cancel list = []
  new() = Cancel(null)
  /// Check if token was cancelled
  member __.Cancelled = flag = 1
  /// Remove child token
  member private __.RemoveChild(child) = 
    let rec loop child =
      let children' = children
      let nval = children' |> List.filter ((<>) child)
      if not (obj.ReferenceEquals(children', Interlocked.CompareExchange(&children, nval, children')))
      then loop child
    if not (List.isEmpty children) then loop child
  /// Create a new child token and return it.
  member this.AddChild () =
    let rec loop child =
      let children' = children
      if (obj.ReferenceEquals(children', Interlocked.CompareExchange(&children, child::children', children')))
      then child
      else loop child
    loop (Cancel this)
  /// Cancel a token
  member this.Cancel() =
    if Interlocked.Exchange(&flag, 1) = 0 then
      for child in Interlocked.Exchange(&children, []) do child.Cancel()
      if not (isNull parent) then parent.RemoveChild(this)

The general idea is simple: every new cancellation token (except root) may have a parent and a list of children. Canceling parent means canceling its children as well. After cancellation, we need to unpin child from its parent (therefore need for RemveChild operation) to avoid memory leaks.

¶Lock-free updates

What might be confusing for some in the code above, are recursive loops inside of AddChild/RemoveChild operations. This is a good place to introduce lock-free algorithms: we use atomic operations from Interlocked class to make sure that we can replace field references within a single CPU instruction, therefore making such field update safe without synchronized access. This is also known as Compare-And-Swap semantics.

This alone however is not enough, as Interlocked.CompareExchange(&field, new', old) can only safely replace a single field with new value if it contained an old one. This means that you cannot safely add or remove element to the list. So what can we do?

1. We’re taking a value from the field.
2. Update that value.
3. Conditionally put it back again. What if in the meantime the field was already replaced by another concurrently running thread? In that case Interlocked.CompareExchange will return field value other that the one we read in step 1. This is why we compare its result with the variable we expected.
4. If the expectation fails, we’ll retry - hence a recursive loop. Eventually even in high contention scenarios we should be able to complete after few retries. Given cheap and idempotent update operation, this still will be way faster than trying to call kernel code to obtain mutex/semaphore lock.

While this may sound like something error prone - we can potentially add the same element multiple times - in practice it’s safe, because our collection here is an immutable data structure. Adding the same element multiple times without updating the reference will always produce the same result.

¶Back on track…

Now we have pretty much all core structures. We’re ready to start building our fiber operators. Starting from the basic ones - a successfully completed fiber and the failed one:

let success r = Fiber <| fun (_, c) next -> 
  if c.Cancelled then next None else next (Some (Ok r))

let fail ex = Fiber <| fun (_, c) next -> 
  if c.Cancelled then next None else next (Some (Error ex))

Here, we simply pass a result/error to our Fiber callback:

• Cancelled fiber call next callback with None - as fibers cancelled before completion produce output .
• Successful call results in passing Some (Ok result) to a callback…
• … while failed result can be identified with Some (Error exception).

You’ll be able to see a cancellation check made here as preamble of pretty much every operator body, which we’ll define. While it may sound cumbersome remember: we do that so that users of our fibers won’t have to :)

Next very important operation is result mapping - we want to map result of one fiber into something else, returning another (lazy) fiber:

let mapResult (fn: Result<'a> -> Result<'b>) (Fiber call) = Fiber <| fun (s, c) next ->
  if c.Cancelled then next None
  else 
    try 
      call (s, c) (fun result ->
        if c.Cancelled then next None
        else next (Option.map fn result))
    with e -> next (Some (Error e))

We can use this function to compose more traditionally-looking map function…

let map (fn: 'a -> 'b) fiber = mapResult (Result.map fn) fiber

… however mapResult is more powerful - you could easily imagine using to apply failure recovery (a.k.a try/catch semantics) by simply mapping Error exception → Ok recoveredValue:

let catch fn fiber = mapResult (function Error e -> fn e | ok -> ok) fiber

Another must-have function is binding operator (also know as flatMap in other languages like Scala, or Promise.then in JavaScript). It gives us the ability to compose fibers together - we’ll also use it when we come up to building a computation expression for our fibers.

let bind (fn: 'a -> Fiber<'b>) (Fiber call) = Fiber <| fun (s, c) next ->
   if c.Cancelled then next None 
   else 
     try
       call (s, c) (fun result ->
         if c.Cancelled then next None
         else match result with
              | Some (Ok r) ->
                 let (Fiber call2) = fn r
                 call2 (s, c) next // pass `next` callback over to next fiber
              | None -> next None
              | Some (Error e) -> next (Some(Error e)))
     with e -> next (Some(Error e))

It’s simple - we execute one fiber from within another, passing the next callback from outer function as an argument to inner one.

¶Fiber computation expressions

With these few functions we’re already prepared to build a basic computation expression, that will enable us programming with fibers in pleasant way:

[<Struct>]
type FiberBuilder =
    member inline __.Zero = Fiber.success (Unchecked.defaultof<_>)
    member inline __.ReturnFrom fib = fib
    member inline __.Return value = Fiber.success value
    member inline __.Bind(fib, fn) = Fiber.bind fn fib

[<AutoOpen>]
module FiberBuilder =

    let fib = FiberBuilder()

While in F# there are many more operators we could pack into our computation expression, these are basic ones that will let it work. With such construct, we’ll be able to write programs like:

let inline millis n = TimeSpan.FromMilliseconds (float n)

let program: Fiber<int> = fib {
  let a = fib {
    do! Fiber.delay (millis 1000) // create some artificial delay
    return 3
  }
  let! b = a |> Fiber.timeout (millis 3000) // execute task within specified timeout
  return b }

Sure, we have neither delay nor timeout operators at the moment, but at least you know where are we heading now :)

¶Delayed execution

In order to implement delays, we could theoretically just call Thread.Sleep and get over it, but this approach is devastating from any coroutine library point of view. Most user-space thread libraries work by using a predefined fixed pool of OS-level threads and scheduling coroutines on them - you can read more about building thread pools here.

However, Thread.Sleep(timeout) doesn’t know thread pooling mechanism - all it knows about is that we called suspending current OS thread of execution. This means, that this thread will not be awoken by kernel until timeout completes. What it means, is that none of our fibers will be able to use that thread. This is bad, because usually thread pools are made to fit in-line with number of machine CPU cores. In practice, Thread.Sleep may keep one of our CPU cores idle, wasting machine power in the process.

For this reason we usually want to build a suspendable fibers, that will respect our thread pool. This however cannot be done without cooperation with scheduler itself. Therefore, we need to extend API of our scheduler:

type IScheduler =
  abstract Schedule: (unit -> unit) -> unit
  abstract Delay: TimeSpan * (unit -> unit) -> unit

And our simple implementation of it as well:

let shared = 
    { new IScheduler with
      member __.Schedule fn = ....
      member this.Delay (timeout: TimeSpan, fn) = 
        let mutable t = Unchecked.defaultof<Timer>
        let callback = fun _ -> 
          t.Dispose()
          fn()
          ()
        t <- new Timer(callback, null, int timeout.TotalMilliseconds, Timeout.Infinite)
    }

We’ll use a .NET timers here to implement our delays. With these in our hands, ourFiber.delay operation is trivial to implement:

let delay (timeout): Fiber<unit> =
  Fiber <| fun (s, c) next ->
    if c.Cancelled then next None
    else s.Delay(timeout, fun () -> 
      if c.Cancelled 
      then next None 
      else next (Some (Ok ())))

¶Composing parallel fibers

We’re slowly getting to the end. What I left for this blog post was to implement two basic operators, that are prevalent in most coroutine libraries:

• Fiber.parallel which will schedule multiple fibers to run in parallel and returns a fiber which aggregates their results.
• Running two fibers in parallel and returning the result of whichever completes first, while cancelling a second one. We already discussed this approach before. Here I’ll call it Fiber.race.

¶Aggregating parallel results

We’ll start from building a parallel operator, which will change our array of fibers into fiber with an array of results. But let’s define the semantics of that operation first:

• Our result fiber completes only when all of the aggregated fibers completed with successful result.
• If any of the fibers fails, the resulting fiber also fails.
• If any of the fibers fails or get cancelled, all pending ones are also cancelled.

The core skeleton of that operation could look like following:

let parallel (fibers: Fiber<'a>[]): Fiber<'a[]> =
  Fiber <| fun (s, c) next ->
    if c.Cancelled then next None
    else 
      let child = c.AddChild()
      let successes = Array.zeroCreate remaining
      let mutable remaining = Array.length fibs
      fibers |> Array.iteri (fun idx (Fiber call) ->
        s.Schedule (fun () -> (* to be defined *))
      )

Here, we create a dedicated cancellation token, an array of results and a countdown counter - we’re going to decrement it every time one of our fibers completes to know when we’re ready to return a complete result. I’ve left a placeholder for a lambda body that we actually want to schedule. We’re going to fill it right away:

// defined above: s.Schedule <| fun () ->
call (s, child) (fun result -> 
match result with
| Some (Ok success) ->
  // fill the result array
  successes.[idx] <- success
  if c.Cancelled && Interlocked.Exchange(&remaining, -1) > 0 then
    next None
  elif Interlocked.Decrement(&remaining) = 0 then
    // if all results have been returned, call the `next` callback
    if c.Cancelled then next None
    else next (Some (Ok successes))
| Some (Error fail) ->
  if Interlocked.Exchange(&remaining, -1) > 0 then 
    child.Cancel() // we failed, cancel other fibers
    if c.Cancelled then next None
    else next (Some (Error fail))
| None ->
  if Interlocked.Exchange(&remaining, -1) > 0 then next None)

As you probably noticed, we’re using Interlocked class again - that’s because now we have multiple fibers running in parallel, therefore our access to shared mutable values is not thread safe. This includes remaining counter decrement operation. This however doesn’t apply to successes.[i] <- success - since every fiber knows and touches only its own index within result array, there’s no worry that any other will try to push its result in the same place.

What you also can see, we’re using a -1 here as a magic value - we’ll use it on the counter as a flag to determine if any of the fibers failed/was cancelled - and if so, which one of them will call the next callback.

¶Racing to completion

With first operator (Fiber.parallel) ready, now it’s the time to implement Fiber.race. Since I’ve discussed it behavior multiple times in this post already, let’s dive straight into the code:

let race (Fiber left) (Fiber right): Fiber<Choice<'a, 'b>> =
  Fiber <| fun (s, c) next ->
    if c.Cancelled then next None
    else 
      let mutable flag = 0
      let cancelChild = c.AddChild()
      let run fiber choice =
          (* to be described *)
      run left Choice1Of2
      run right Choice2Of2

So again, we want to have shared mutable flag, which we’ll use to determine, which of the fibers finished as a first one to be able to call fiber’s callback safely and cancel the other. You may see, that our returned fiber uses Choice<,> type - this means, that our left and right fibers can have results of different types. We’ll use that soon, but first we need to complete our run function body:

let run fiber choice =
  s.Schedule (fun () ->
    fiber (s, cancelChild) (fun result ->
      if Interlocked.Exchange(&flag, 1) = 0 then
        cancelChild.Cancel()
        if c.Cancelled then next None
        else match result with
             | None -> next None
             | Some(Ok v) -> next (Some(Ok(choice v)))
             | Some(Error e) -> next (Some(Error e))))

What we do here is simply trying to race to “reserve” out flag variable - the winner gets his result mapped to corresponding choice, while looser gets cancelled.

What’s interesting, we can now combine our race and delay functions to easily implement timeout mechanism:

let timeout (t: TimeSpan) fiber =
  Fiber <| fun (s, c) next ->
    let (Fiber call) = race (delay t) fiber
    call (s, c) (fun result ->
      if c.Cancelled then next None
      else match result with
           | None -> next None
           | Some(Ok (Choice1Of2 _)) -> next None // timeout won
           | Some(Ok (Choice2Of2 v)) -> next (Some(Ok v))
           | Some(Error e) -> next (Some(Error e))
    )

The one last thing left for us, is to be able to run out fibers on the main thread - otherwise we’d start our program, schedule fibers to run in the background and then close the program without waiting for the results.

let blocking (s: IScheduler) (cancel: Cancel) (Fiber fn) =
  use waiter = new ManualResetEventSlim(false)
  let mutable res = None
  s.Schedule(fun () -> fn (s, cancel) (fun result ->
    if not cancel.Cancelled then
      Interlocked.Exchange(&res, Some result) |> ignore
    waiter.Set()))
  waiter.Wait()
  res.Value

It’s simple - we’ll use standard synchronization primitives provided by .NET runtime, to hold current OS thread until we complete. Sure it’s blocking an OS thread, but we’ll eventually need that if we don’t want our program’s main function to finish before all fibers inside the thread pool complete.

¶Simulating real environment in tests

In theory, we could be done here. But, if you managed to read up to this point, we may want to cover one last scenario. Imagine that we’d want to test our fibers. However running tests using standard thread pool scheduler can lead to funky issues:

• Sometimes you may trigger some race conditions in your code, that only happen in specific situations (like high CPU contention) and are almost impossible to reproduce during debug sessions.
• Other times you may have some lengthy delays/timeouts in your code, like waiting for seconds or even minutes before continuing. Guess what: now your test will wait for just as long.

These are not new problems. They are well known in world of concurrent and distributed systems. What we need, is a simulation of execution environment. If you want to listen more about that concept, I could recommend you this presentaton. To run our test predictably, we’ll create a dedicated test scheduler, which will run our code in deterministic fashion (on a single core) and in a way that’s detached from other invariants eg. actual physical clock and random number generator.

The idea here is simple - our scheduler will operate on notion of virtual timeline. When we’ll try to schedule a new function - to trigger either immediately or after some timeout - we’ll store it inside an ordered collection, a timeline. Some of the technical decisions we also made for purposes of this implementation:

• Whenever a fiber is going to schedule multiple parallel executions “at the same time”, we’ll put them all into a single bucket on a timeline. Later on I’ll cover, why this is useful.
• We’ll assume, that single operation execution is instantaneous. It means, it doesn’t advance our scheduler’s clock. We do it only for delayed executions.

After describing the concept behind the algorithm, the actual implementation really shouldn’t be that surprising:

type TestScheduler(now: DateTime) =
  let mutable running = false
  let mutable currentTime = now.Ticks
  let mutable timeline = Map.empty
  let schedule delay fn = (* to be defined *)
  let rec run () = (* to be defined *)
  interface IScheduler with
    member this.Schedule fn = 
      schedule 0L fn
      if not running then
        running <- true
        run ()
    member this.Delay (timeout: TimeSpan, fn) = schedule timeout.Ticks fn

We’re using a running flag here to not try to invoke run multiple times in nested manner - this would cause non-tailable recursion and potential stack overflow in more expensive tests.

The schedule function is pretty simple - calculate expected execution time for a function, then add that function to be executed at that point in time.

let schedule delay fn = 
  let at = currentTime + delay
  timeline <-
    match Map.tryFind at timeline with
    | None -> Map.add at [fn] timeline 
    | Some fns -> Map.add at (fn::fns) timeline

Given all of the code we already survived in this blog post, run loop should be pretty simple:

let rec run () =
  match Seq.tryHead timeline with
  | None -> running <- false
  | Some (KeyValue(time, bucket)) ->
    timeline <- Map.remove time timeline
    currentTime <- time
    for fn in List.rev bucket do 
      fn ()          
    run ()

We’ll try to pick the first entry from the timeline - since here we use F# map, which is sorted in ascending order, we know that first entry is the one with the shortest execution timeout. We update our “current” time to match the expected one we calculated earlier, and finally we execute all functions scheduled at that time and repeat the loop all over until we eventually run out of scheduled actions.

Now here’s the trick - we use List.rev to execute functions in the same order in which they were scheduled, because we want our tests to be deterministic and our bugs to be reproducible. However this is not the only strategy - since we know that functions in the same bucket could as well be executing in parallel, we could shuffle them around in different permutations for early discovery of some data races! I’ll won’t dive into it, but leave that idea as food for thoughts for you.

One last note about the test scheduler is that isolating it from the actual physical clock means, we cannot trust our time functions (like DateTime.UtcNow) any longer. This shouldn’t really be an issue though - because relying on physical time would potentially make our tests indeterministic, we didn’t want to use it anyway, right?

However, we need to be able to obtain current time from the scheduler, so we need to extend its API:

type IScheduler =
  abstract UtcNow: unit -> unit
  // ... other methods
  
type TestScheduler() =
  let mutable currentTime = DateTime.UtcNow.Ticks
  // ... rest of the implementation
  interface IScheduler with
    member __.UtcNow() = DateTime(currentTime)
    // ... other methods

And that’s all. As always, if you got confused or have a problems along the way, you can get the entire code here. I wanted to thank to Anthony Lloyd for his initial work on porting Scala ZIO library to F#, which brought me an inspiration to write this piece.

一般来说，Ubiquitous Language 有以下特点：

1. 共享：Ubiquitous Language 是由开发团队和业务专家共同创建和使用的。它不仅用于代码和文档，还用于日常的沟通和讨论。
2. 统一：在整个项目中，Ubiquitous Language 应该是一致的。无论是在代码、文档、会议还是白板上，都应该使用相同的术语和概念。
3. 精确：Ubiquitous Language 应该尽可能精确，避免模糊和歧义。每个术语都应该有明确的定义和含义。
4. 演进：Ubiquitous Language 是动态的，会随着项目的进展和业务需求的变化而演进。团队应该定期审查和更新它。

基于此，它可以用在这些地方：

1. 命名：在代码中使用 Ubiquitous Language 来命名类、方法、变量等。例如，如果业务专家使用“订单”来描述一个概念，那么在代码中也应该使用“Order”而不是“Purchase”或“Transaction”。
2. 文档：在文档中使用 Ubiquitous Language 来描述系统的设计、架构和功能。这有助于业务专家更容易理解技术文档。
3. 沟通：在团队会议、讨论和白板会议中使用 Ubiquitous Language。这有助于确保所有参与者都在讨论同一个概念。
4. 测试：在编写测试用例时，使用 Ubiquitous Language 来描述测试的前提条件、步骤和预期结果。这有助于确保测试覆盖了业务需求。

假设正在开发一个电子商务系统，业务专家使用“订单”来描述用户购买的商品集合。团队可以在代码中使用“Order”来命名相关的类和方法：

type Order = {
    items: OrderItem list
    customer: Customer
    orderDate: DateTime
}

type OrderItem = {
    product: Product
    quantity: int
}

type Customer = {
    name: string
}

type Product = {
    name: string
    price: float
}

let addItem (order: Order) (item: OrderItem) =
    { order with items = order.items @ [item] }

let getTotalAmount (order: Order) =
    let total = 0.0
    for item in order.items do
        total <- total + item.price
    total

let getPrice (item: OrderItem) =
    item.product.price * item.quantity

let getTotalPrice (order: Order) =
    let total = 0.0
    for item in order.items do
        total <- total + getPrice(item)
    total

在这个示例中使用了“Order”、“OrderItem”、“Customer”和“Product”等术语，这些术语都是 Ubiquitous Language 的一部分，可以提高代码与业务需求的一致性。

Managing code dependencies in object oriented languages in 2020 is pretty much one sided problem: dependency injection has won, people use dedicated frameworks to handle that for them, which 99.9% of the time operate using runtime reflection. Of course now you need to learn them as well, potentially misconfigure them and fail at runtime or maybe even discover that not every problem is a stateless web service, but it still better (?) than what we had in the past, and what more can we possibly do anyway?

On the other side in functional space, there’s no one opinionated solution or approach - various things have been proposed, usually depending on features that languages and compiler have to offer. And since pretty much all functional languages offer this thing known as partial application, for many years it was the most common answer for the problem of managing dependencies.

In short we’re talking about dependency injection by function parameter, like:

// foo requires 2 dependencies to serve the incoming request
let foo bar baz request = ???
// we're providing dependencies by partial application
let wired = foo dependency1 dependency2
// now wired can serve request directly without calling 
// dependencies every time
let response = wired request

It’s very simple, doesn’t require reflection or dedicated library. However there are several pain points coming with this approach - visible especially as our code base grows and become more complex. However latest approaches popularized by libraries like Scala ZIO or Haskell’s Polysemy challenge this approach.

¶Partial application

There are some design decisions, when partial application doesn’t always give a clear answer. Example:

Imagine using a set of methods, that are closely related and - in object oriented world - encapsulated within  a single object, like database query/execute or different logging methods (debug/info/warning/error).

Now, given that our function needs to use potentially more than one of these, how should we pass our arguments?:

1. Functional purist path - pass every dependency as a separate function parameter: let doSmth logError logInfo = ??. While it allows us to precisely describe what this function uses, it would of course lead to explosion of function parameters. Additionally every time you need new function in your existing code, you need to partially apply it at all call sites.
2. Describe operations using ADT (algebraic data types) and inject a function that will work as an interpreter for them: let doSmth (log: LogEvent -> unit) = ??. While it’s easy to mock (you don’t need to implement everything, only pattern match on cases that matter for a particular test) and reduces params affinity, it also comes with a lot of indirection, that may lead to harder to grasp, especially during debugging. Sometimes a performance penalty is also to be expected.
3. Fallback to objects/interfaces and pass them as methods: let doSmth (logger: ILogger) = ??. While interfaces may simplify dependency tree, it’s not always obvious when to use it. Mocking story is also more painful + interfaces are not inferred by F# compiler.

These are quite common options I’ve seen in the wild - each having their own advantages and disadvantages. Which one to use? Good question, as in practice with codebases that are old enough, you usually see 2 or even all 3 of them mixed together. This can lead to some confusion and obscurity over time.

What’s worse, none of these cases really solves problem of dependency management - all they do is just try to reduce it to a manageable scope. Eventually you’ll end up manually wiring - by partial application - dozens of functions and managing all of the dependencies between them by hand.

¶Example

In order to get better understanding, we’ll use a fairly simple example - changing user password:

let fetchUser (db: IDbConnection) userId = 
    db.QueryFirstAsync(Sql.FetchUser, {| userId = userid| })
    
let updateUser (db: IDbConnection) user = db.ExecuteAsync(Sql.UpdateUser, user)

let changePass (logger: ILogger) fetch update = fun req -> task {
    let! user = fetch req.UserId
    if user.Hash = bcrypt user.Salt req.OldPass then
        let salt = generateSalt ()
        let user' = { user with Salt = salt; Hash = bcrypt salt req.NewPass }
        do! update user'
        logger.LogInformation "Password change: user %i" user.Id
        return Ok ()
    else 
        logger.LogError "Password change unauthorized: user %i" user.Id
        return Error "Old password is invalid"
}

Here we have a fairly short snippet with some dependencies? But how many in practice?:

• Number of parameters suggest 3, but depending on our choices it could be 4 (if we decide to pass log error and info separately) or 2 (if we conflate fetch/update into dedicated interface).
• It’s not hard to imagine that in the future our bcrypt hashing function may turn out to be configurable - maybe even per each user. That may need a configurable parameter.
• Maybe aside of the logger we may be needing a separate telemetry mechanism to count number of incoming request or password validation failures? That means another parameter.
• Salt generation is pseudo-random process - it we want our function to be deterministic, we should probably parametrize it over explicitly passed Random as well.

As you see, what seemed to be simple task at the beginning can quickly blow up out of proportion. As the number of arguments grows, the more nasty our wiring code eventually becomes. Quite common pattern is to hide all of that nastiness under the carpet a.k.a. composition root. However this doesn’t have to be the case.

Below we’ll cover another approach for dealing with dependencies - inspired by Scala ZIO library - using incremental steps, from first principles to monadic bindings.

¶Managing dependencies beyond partial application

Let’s start from how our code from above will eventually look like at the end of this step:

let changePass env = fun req -> task {
    let! user = Db.fetchUser env req.UserId
    if user.Hash = bcrypt user.Salt req.OldPass then
        let salt = Random.bytes env 32
        do! Db.updateUser env { user with Salt = salt; Hash = bcrypt salt req.NewPass }
        Log.info env "Changed password for user %i" user.Id
        return Ok ()
    else 
        Log.error env "Password change unauthorized: user %i" user.Id
        return Error "Old password is invalid"
}

As you may notice, all of our partially applied parameters disappeared, replaced by some single cryptic env parameter. We’ll get there soon. We also packed similar capabilities into corresponding modules (Db/Log/Random). Lets start from defining them:

[<Interface>]
type ILogger =
    abstract Debug: string -> unit
    abstract Error: string -> unit 

[<Interface>] type ILog = abstract Logger: ILogger

module Log =
    let debug (env: #ILog) fmt = Printf.kprintf env.Logger.Debug fmt
    let error (env: #ILog) fmt = Printf.kprintf env.Logger.Error fmt

Now we can say something more about env. The secret is in #ILog signature, which means that our environment can be any generic type implementing ILog interface. As soon you’ll see, this approach is highly composable, but before that we’ll need another module:

[<Interface>]
type IDatabase =
    abstract Query: string * 'i -> Task<'o>
    abstract Execute: string * 'i -> Task
	
[<Interface>] type IDb = abstract Database: IDatabase

module Db = 
    let fetchUser (env: #IDb) userId = 
        env.Database.Query(Sql.FetchUser, {| userId = userId |})
    let updateUser (env: #IDb) user = env.Database.Execute(Sql.UpdateUser, user)

Now what will happen if we use functions from both Log and Db modules? As it turns out, F# compiler can properly infer generic constraints over these interfaces. The result env type constraint is inferred to be an union - just like set union, which also means that it handles duplicates for us - of all constraints of other functions using env in its scope:

let foo env = // env :> IDb and env :> ILog
    let user = Db.fetchUser env 123	// env :> IDb
    Log.debug env "User: %A" user	// env :> ILog

Now why did we use two separate interfaces (ILog/ILogger) instead of making environment implement ILogger directly? This is more practical approach that will let us isolate capabilities of particular modules rather than putting them flat into our environment. Example:

module Log =
    let live : ILogger = ?? // create logger interface

[<Struct>]
type AppEnv = 
    interface ILog with member _.Logger = Log.live
    interface IDb with member _.Database = Db.live connectionString
	
foo (AppEnv())

We cannot eagerly provide a specific implementation of ILog/IDb, because they’re yet to be defined as part of by our environment type (which may need to implement many interfaces). To maintain module encapsulation Log module shouldn’t be aware of existence or implementation of IDb interface and vice versa for Db module. What we can do however is to provide live implementation of ILogger, which encapsulates capabilities required by the Log module. This way we don’t need to know details of ILogger when defining our environment type.

Strong sides of this approach?:

• We only need to provide a single environment object instead of (potentially) unbounded list of parameters. Since it’s always one, it’s easier to generalize and compose other functions over it.
• Unlike in reflection-based dependency injection frameworks - everything is still safe and checked by the compiler. If our environment type will not implement an interface required somewhere in the call chain, our code will simply not compile.
• It’s still fairly easy to unit test - each function defines only the generic type constraints that it uses in its own call tree, NOT all of the constraints required by the application.
• New dependencies are added implicitly - if your code uses module that requires additional capability, it will be automatically inferred by the compiler and bubble up to our environment type definition. No need to add new function parameters or to pass new argument. Also - unlike the object oriented IoC containers - there’s no need to add new dependency as a field or constructor argument.
• It gives some opinionated approach on what should be a dependency - less thinking of “should that be a function or interface?” or “if these two functions correspond to the same capability, should they be passed separately?”, which arguably may be a good thing.
• It doesn’t impose specific restrictions on libraries and frameworks.

Now we could as well stop here - IMHO this approach is already good and useful for most cases. We can also try to push it further. As you’ve seen, our code now requires quite a lot of env passing around. Could we do something about this? It turns out that yes, we could.

¶Reader monad

Before we continue: what we’re going to cover now is less useful in terms of current state of F# ecosystem for the reasons I’ll mention later.

The pattern we’ll use here is known as a Reader Monad. While it’s useful in certain situations, it’s not widely used - IMO it’s fault lies in the name itself, which somehow managed to sound both borderline meaningless and scary in ears of many developers.

The rest of this blog post will be introduction to this style in F#, however focused solely around problem of dependency management - we’ll ignore other aspects of monads.

We’ll going to reuse our environment type from above, but now encode it directly into another type we’ll call Effect. Since I’ve mentioned that our pattern has M-word in it, you can safely assume that our handler’s logic will be defined as a lazy sequence of steps to be executed (sounds almost like async/await). In F# we’ll sugar them by using custom computation expression (I’m going to call it effect { ... }) returning our effect type, which we’ll define as:

[<Struct>] type Effect<'env, 'out> = Effect of ('env -> 'out)

Where:

• env is our environment type we already talked about above.
• out defines a returned value type of our effect.

Eventually, with this type in hand our simple request handler will be looking like that:

let changePass req = effect {
    let! user = Db.fetchUser req.UserId
    if user.Hash = bcrypt user.Salt req.OldPass then
        let! salt = Random.bytes 32
        do! Db.updateUser { user with Salt = salt; Hash = bcrypt salt req.NewPass }
        do! Log.info "Changed password for user %i" user.Id
        return Ok ()
    else 
        do! Log.error "Password change unauthorized: user %i" user.Id
        return Error "Old password is invalid"
}

As you see, there’s no more env parameter being passed around. It’s now an implicit part of our effect expression. However at the moment we didn’t provide enough infrastructure in our code to make that thing work. What we’re going to need is a set of operators, we can use to make our computation expression happen.

First we’re going to need some Effect<'env,'out> constructors:

module Effect =
    /// Create value with no dependency requirements.
    let inline value (x: 'out): Effect<'env,'out> = Effect (fun _ -> x)
    /// Create value which uses depenendency.
    let inline apply (fn: 'env -> 'out): Effect<'env,'out> = Effect fn

We also need some way to run our effect to be able to make it… well effectful:

module Effect =

	(* ...other functions... *)
	
    let run (env: 'env) (Effect fn): 'out = fn env

And since we already mentioned Effect is monad, we also gonna need a bind function as well if we want to compose our effects together:

module Effect =

	(* ...other functions... *)
	
    let inline bind (fn: 'a -> Effect<'env,'b>) effect =
        Effect (fun env ->
            let x = run env effect // compute result of the first effect
            run env (fn x) // run second effect, based on result of first one
        )

This is pretty much it. We’re just going to add compose all of these into builder type to make it usable as F# computation expression:

[<Struct>]
type EffectBuilder =
    member inline __.Return value = Effect.value value
    member inline __.Zero () = Effect.value (Unchecked.defaultof<_>)
    member inline __.ReturnFrom (effect: Effect<'env, 'out>) = effect
    member inline __.Bind(effect, fn) = Effect.bind fn effect
    
let effect = EffectBuilder()

Of course this, we still need to adapt the modules we prepared earlier to now operate on effects rater than plain functions. We can make this easier by using our Effect.apply function, like:

module Log =    
    let debug fmt =
        let ap s = Effect.apply (fun (x: #ILog) -> x.Logger.Debug s)
        Printf.kprintf ap fmt

So - as you may have noticed in final form of our effect-based changePass function - in result we almost fully erased all of the dependency-wiring code from our example. There are several downsides of this approach:

• We do a lot of more bindings (see let!/do! expressions), which means more lambda closures, indirection (wait to see call stacks) and more allocations.
• Altogether we also erased task { ... } computation expression and with it an out-of-the-box ability to write asynchronous code. This is one of the downsides of using monads - cross-type composition is painful.

Of course we could enrich our Effect type to be able to bind it with Task/Async. That however means, that our pattern grows in complexity and becomes more of a framework rather than something to be easily applied into existing code. Is that bad? Not necessarily, but for sure comes with a bigger commitment, as now you’re not only writing business logic but eventually maintain new effect library. Maybe in future this concept will grow into its own space in favor of the F# ecosystem.

¶Summary

We came from partial application as tool for dependency injection, over more structured approach promoting single environment type with help of powerful F# type inference, up to encapsulating it into a Reader Monad. That’s a long way. I hope you’ll give it a try and it will help you determine the approach that works for you.

open System
open System.Numerics

let someFunction () =
    let v: Vector<byte> = Vector(0uy)
    let array: byte[] = [||]
    let span: Span<byte> = Span(array)
    v.CopyTo(span)
Compiler error
     v.CopyTo(span)
  ----^^^^^^^^^^^^^^

/home/muqiu/stdin(99,5): error FS0041: A unique overload for method 'CopyTo' could not be determined based on type information prior to this program point. A type annotation may be needed.

Known type of argument: Span<byte>

Candidates:
 - Vector.CopyTo(destination: Span<byte>) : unit
 - Vector.CopyTo(destination: Span<byte>) : unit

编译器认为存在两个相同的 CopyTo 重载无法区分。但查阅文档发现，Vector<T> 的 CopyTo 方法实际上只有一个匹配的重载（接受 Span<T>），这似乎矛盾。

这是因为 F# 编译器处理泛型方法重载的方式：

• 泛型接口继承：Vector<T> 可能实现了多个接口，导致编译器看到两个签名相同的 CopyTo 方法（例如通过不同接口继承）。
• 语言设计差异：F# 缺乏 C# 的 “most concrete” 重载选择机制。当多个重载来自不同继承路径时，F# 不会自动选择最具体的实现，需要显式指引。

仅我所知的一种解决方案是通过添加扩展方法显式指引编译器：

type Vector<'T> with
    member inline this.CopyToByteSpan (span : Span<byte>) = 
        this.CopyTo(span) // 显式绑定具体重载

// 调用时使用新方法
v.CopyToByteSpan(span)

这种方法通过创建具体的类型路径，帮助编译器绕过复杂的重载解析逻辑。

学艺不精，不知道这是不是语言设计的差异，可能 F# 倾向于要求更明确的类型信息以避免意外行为？或许当泛型类型继承多个接口时，有没有可能出现在具体类型中不易察觉的隐式重载冲突？

¶Refs.

• “Most concrete” tiebreaker for generic overloads #905
• Fail to resolve to non generic overload. #1647

在FDA监管的药物研发、临床试验和上市流程中，当一个已上市药物（通常指创新药，通过新药申请NDA获得批准）出现一种更低廉的制药方式，但其活性成分的分子式保持完全相同时，这种情况本质上涉及仿制药（generic drug）的开发或工艺优化申请，而非从零开始的全新药物研发。简单来说，不需要重新进行完整的临床试验（即I-III期的大规模人体试验），但必须通过简化的监管路径证明新制药方式生产的药物与原药在质量、安全性和疗效上等效。

首先，理解核心前提：分子式完全相同意味着活性成分（active pharmaceutical ingredient, API）是相同的化学实体，例如从专利保护的原研药转向无专利保护的仿制药生产。这不同于生物制品（如单克隆抗体）的生物类似药，后者可能需要更多比较性临床试验。FDA将此类药物归类为“仿制药”，其审批路径是缩减新药申请（Abbreviated New Drug Application, ANDA），而非完整的NDA。ANDA的目的是避免重复证明已知的安全性和有效性数据，这些数据已在原药的NDA中确立^[1]。

FDA的《仿制药用户费用法案》（GDUFA）和相关指南明确规定，对于相同分子式的药物，新制药方式（如改进的合成路线、晶型优化或更高效的提取工艺）只需证明“生物等效性”（bioequivalence），而非全面临床试验。生物等效性研究通常包括：1）体外溶出测试（in vitro dissolution），评估药物在模拟生理条件下的释放速率；2）人体药代动力学研究（pharmacokinetic studies），在健康志愿者中比较新药与原药的吸收、分布、代谢和排泄曲线（如AUC和Cmax参数的90%置信区间在80%-125%内）。这些研究规模小，通常只需24-36名受试者，持续数周，而非数年^[2]。如果新工艺导致杂质谱或稳定性变化，FDA可能要求额外的数据，如加速稳定性测试或毒性评估，但仍无需重复疗效试验，除非有证据显示潜在差异（如新杂质超过许可阈值）^[3]。

在实际操作中，这一路径大大降低了成本和时间：ANDA审批平均需10-15个月，费用远低于NDA的数亿美元和数年周期。新制药方式的低廉性往往源于规模化生产或工艺创新，但FDA要求申请者提交化学、制造和控制（CMC）信息，证明新工艺符合良好生产规范（cGMP）。例如，阿司匹林或扑热息痛等经典药物，其多种仿制药版本均通过此路径上市，而无需重新验证其止痛或抗炎疗效^[4]。然而，如果新方式涉及重大变更（如从化学合成转为生物合成，尽管分子式相同），FDA可能视其为“混合型”申请，需要桥接研究来确认等效性。

如果生物等效性未能证明（例如，新工艺导致生物利用度差异>20%），申请将被拒，或需额外桥接试验，这可能增加延误和成本。不过上市后监测（post-marketing surveillance）仍适用，包括不良事件报告（FAERS系统），以捕捉任何罕见差异。

FHIR 中的药物相关记录类型本质上是是状态机（State Machine）和责任链（Chain of Responsibility）。每个资源代表业务流程中的一个特定状态（如“已下达”、“已执行”、“已陈述”），并通过引用链接形成完整的、可审计的责任链。以下是基于此原理的决策逻辑与实现方案。

¶核心逻辑：根据数据源的意图选择资源

用药信息的记录遵循“谁在什么时间点产生了什么信息”的原则。这直接对应到三个核心资源：

1. MedicationRequest（用药请求）

   • 意图与状态：代表一个临床意图或指令。这是一个对未来行为的请求，其状态包括 active（激活）、completed（完成）、cancelled（取消）等。
   • 数据来源：由具有处方权的医疗专业人员（如医生）创建。
   • 核心信息：包含用药方案（药品、剂量、频次、途径）、用药原因、有效时间段、开立者、开立时间。
   • 类比：医院的“医嘱单”或药房的“处方”。

2. MedicationAdministration（用药管理）

   • 意图与状态：代表一个已发生的事实。这是对MedicationRequest指令的一次具体执行事件的记录，状态为 completed。
   • 数据来源：由执行给药的医疗专业人员（如护士）在给药后记录。
   • 核心信息：包含实际使用的药品、实际剂量、实际给药时间、给药途径、执行者。它必须通过 .basedOn 字段引用一个或多个MedicationRequest，以建立从“指令”到“执行”的可追溯性。
   • 类比：护士的“给药记录”，精确到某年某月某日某时某分给患者注射了某药。

3. MedicationStatement（用药陈述）

   • 意图与状态：代表一个关于用药的断言或声明。它描述的是患者正在使用、曾经使用或计划使用某种药物的状态，不一定关联到具体的医嘱。
   • 数据来源：可以来自患者自述（如“我每天吃一粒阿司匹林”）、家属转述，或由系统从历史记录中汇总生成。
   • 核心信息：包含陈述的用药信息、有效时间段、信息状态（如 active, completed）、信息来源（patient-reported）。
   • 类比：病历中的“现病史-用药史”部分，或患者填写的“用药清单”。

一个完整的院内用药闭环通常遵循以下可追溯的数据流：

graph LR
    A[医生创建
MedicationRequest] -- `.basedOn` 引用 --> B[护士执行后创建
MedicationAdministration];
    B -- 系统可推导生成 --> C[系统生成
MedicationStatement
（汇总当前有效用药）];
    D[患者自述
MedicationStatement] -- 可提供给 --> A;

这种设计确保了数据的不可变性与可审计性。每个事件（开立、执行）作为一个独立的资源被记录，通过引用链形成完整的溯源路径。

• 追求完整审计溯源：必须使用 MedicationRequest + MedicationAdministration 的组合。这引入了更高的系统复杂性，但提供了从医嘱到执行的全链路证据。
• 记录患者用药史或社区医疗场景：使用 MedicationStatement 更为合适和轻量。它牺牲了与具体执行事件的强关联，但能更灵活地捕获患者陈述或汇总的用药信息。
• 一个常见错误是试图用一个 MedicationStatement 来同时扮演“医嘱”和“执行记录”的角色。这会破坏数据模型，导致无法区分“医嘱内容”、“实际执行情况”和“患者陈述”，在出现用药差错时无法进行有效溯源。

¶示例：记录一次门诊处方及取药

1. 医生开处方：创建 MedicationRequest，状态为 active，包含药品、用法用量、开立时间。
2. 药师发药：（若需记录发药行为）可创建 MedicationDispense 资源（另一个相关资源），记录发药时间、数量，并通过 .basedOn 引用上述 MedicationRequest。
3. 患者回家服药：此事件通常不在临床系统直接记录。但患者复诊时，可自述“我按处方吃了药”，此时可创建一条来源为 patient-reported 的 MedicationStatement，通过 .derivedFrom 关联到最初的 MedicationRequest，表明此陈述源于该处方。

Overtime, this definition was considered both too rigid and too ill defined.
Given the impracticality of prolonged hospitalizations and advancing technology for diagnosis, the duration of work up was shortened to 3 days inpatient evaluation and/or 3 outpatient clinic visits.

• Original Document

这是FUO(不明原因发烧)的综合指南，第一个普遍接受的 FUO 定义是1961 年发布的，包括多次发烧超过三十八度三，发烧持续时间至少 3 周，并且就算住院至少 1 周但仍无明确原因。后面这个定义被认为过于僵化且过于模糊。又改成了三天住院评估和/或三次门。除了有关评估持续时间的所有时间要求，还应该将 FUO 定义为完成最低限度检查后缺乏已知病因的发烧。

常见原因就感染性，自身免疫和结缔组织疾病，其他炎症过程和恶性肿瘤。结缔组织疾病和自身免疫性疾病是青少年 FUO 比儿童更常见的原因。
总体上有超过两百种病因可导致 FUO

https://fsharpforfunandprofit.com/posts/concurrency-reactive/

Events are everywhere. Almost every program has to handle events, whether it be button clicks in the user interface, listening to sockets in a server, or even a system shutdown notification.

And events are the basis of one of the most common OO design patterns: the “Observer” pattern.

But as we know, event handling, like concurrency in general, can be tricky to implement. Simple event logic is straightforward, but what about logic like “do something if two events happen in a row but do something different if only one event happens” or “do something if two events happen at roughly the same time”. And how easy is it to combine these requirements in other, more complex ways?

Even if you can successfully implement these requirements, the code tends to be spaghetti like and hard to understand, even with the best intentions.

Is there an approach that can make event handling easier?

We saw in the previous post on message queues that one of the advantages of that approach was that the requests were “serialized” making it conceptually easier to deal with.

There is a similar approach that can be used with events. The idea is to turn a series of events into an “event stream”. Event streams then become quite like IEnumerables, and so the obvious next step is to treat them in much the the same way that LINQ handles collections, so that they can be filtered, mapped, split and combined.

F# has built in support for this model, as well as for the more traditional approach.

¶A simple event stream

Let’s start with a simple example to compare the two approaches. We’ll implement the classic event handler approach first.

First, we define a utility function that will:

• create a timer
• register a handler for the Elapsed event
• run the timer for five seconds and then stop it

Here’s the code:

open System
open System.Threading

/// create a timer and register an event handler,
/// then run the timer for five seconds
let createTimer timerInterval eventHandler =
    // setup a timer
    let timer = new System.Timers.Timer(float timerInterval)
    timer.AutoReset <- true

    // add an event handler
    timer.Elapsed.Add eventHandler

    // return an async task
    async {
        // start timer...
        timer.Start()
        // ...run for five seconds...
        do! Async.Sleep 5000
        // ... and stop
        timer.Stop()
    }

Now test it interactively:

// create a handler. The event args are ignored
let basicHandler _ = printfn "tick %A" DateTime.Now

// register the handler
let basicTimer1 = createTimer 1000 basicHandler

// run the task now
Async.RunSynchronously basicTimer1

Now let’s create a similar utility method to create a timer, but this time it will return an “observable” as well, which is the stream of events.

let createTimerAndObservable timerInterval =
    // setup a timer
    let timer = new System.Timers.Timer(float timerInterval)
    timer.AutoReset <- true

    // events are automatically IObservable
    let observable = timer.Elapsed

    // return an async task
    let task = async {
        timer.Start()
        do! Async.Sleep 5000
        timer.Stop()
    }

    // return a async task and the observable
    (task,observable)

And again test it interactively:

// create the timer and the corresponding observable
let basicTimer2 , timerEventStream = createTimerAndObservable 1000

// register that every time something happens on the
// event stream, print the time.
timerEventStream
|> Observable.subscribe (fun _ -> printfn "tick %A" DateTime.Now)

// run the task now
Async.RunSynchronously basicTimer2

The difference is that instead of registering a handler directly with an event, we are “subscribing” to an event stream. Subtly different, and important.

¶Counting events

In this next example, we’ll have a slightly more complex requirement:

Create a timer that ticks every 500ms.
At each tick, print the number of ticks so far and the current time.

To do this in a classic imperative way, we would probably create a class with a mutable counter, as below:

type ImperativeTimerCount() =

    let mutable count = 0

    // the event handler. The event args are ignored
    member this.handleEvent _ =
      count <- count + 1
      printfn "timer ticked with count %i" count

We can reuse the utility functions we created earlier to test it:

// create a handler class
let handler = new ImperativeTimerCount()

// register the handler method
let timerCount1 = createTimer 500 handler.handleEvent

// run the task now
Async.RunSynchronously timerCount1

Let’s see how we would do this same thing in a functional way:

// create the timer and the corresponding observable
let timerCount2, timerEventStream = createTimerAndObservable 500

// set up the transformations on the event stream
timerEventStream
|> Observable.scan (fun count _ -> count + 1) 0
|> Observable.subscribe (fun count -> printfn "timer ticked with count %i" count)

// run the task now
Async.RunSynchronously timerCount2

Here we see how you can build up layers of event transformations, just as you do with list transformations in LINQ.

The first transformation is scan, which accumulates state for each event. It is roughly equivalent to the List.fold function that we have seen used with lists. In this case, the accumulated state is just a counter.

And then, for each event, the count is printed out.

Note that in this functional approach, we didn’t have any mutable state, and we didn’t need to create any special classes.

¶Merging multiple event streams

For a final example, we’ll look at merging multiple event streams.

Let’s make a requirement based on the well-known “FizzBuzz” problem:

Create two timers, called '3' and '5'. The '3' timer ticks every 300ms and the '5' timer ticks
every 500ms.

Handle the events as follows:
a) for all events, print the id of the time and the time
b) when a tick is simultaneous with a previous tick, print 'FizzBuzz'
otherwise:
c) when the '3' timer ticks on its own, print 'Fizz'
d) when the '5' timer ticks on its own, print 'Buzz'

First let’s create some code that both implementations can use.

We’ll want a generic event type that captures the timer id and the time of the tick.

type FizzBuzzEvent = {label:int; time: DateTime}

And then we need a utility function to see if two events are simultaneous. We’ll be generous and allow a time difference of up to 50ms.

let areSimultaneous (earlierEvent,laterEvent) =
    let {label=_;time=t1} = earlierEvent
    let {label=_;time=t2} = laterEvent
    t2.Subtract(t1).Milliseconds < 50

In the imperative design, we’ll need to keep track of the previous event, so we can compare them. And we’ll need special case code for the first time, when the previous event doesn’t exist

type ImperativeFizzBuzzHandler() =

    let mutable previousEvent: FizzBuzzEvent option = None

    let printEvent thisEvent  =
      let {label=id; time=t} = thisEvent
      printf "[%i] %i.%03i " id t.Second t.Millisecond
      let simultaneous = previousEvent.IsSome && areSimultaneous (previousEvent.Value,thisEvent)
      if simultaneous then printfn "FizzBuzz"
      elif id = 3 then printfn "Fizz"
      elif id = 5 then printfn "Buzz"

    member this.handleEvent3 eventArgs =
      let event = {label=3; time=DateTime.Now}
      printEvent event
      previousEvent <- Some event

    member this.handleEvent5 eventArgs =
      let event = {label=5; time=DateTime.Now}
      printEvent event
      previousEvent <- Some event

Now the code is beginning to get ugly fast! Already we have mutable state, complex conditional logic, and special cases, just for such a simple requirement.

Let’s test it:

// create the class
let handler = new ImperativeFizzBuzzHandler()

// create the two timers and register the two handlers
let timer3 = createTimer 300 handler.handleEvent3
let timer5 = createTimer 500 handler.handleEvent5

// run the two timers at the same time
[timer3;timer5]
|> Async.Parallel
|> Async.RunSynchronously

It does work, but are you sure the code is not buggy? Are you likely to accidentally break something if you change it?

The problem with this imperative code is that it has a lot of noise that obscures the the requirements.

Can the functional version do better? Let’s see!

First, we create two event streams, one for each timer:

let timer3, timerEventStream3 = createTimerAndObservable 300
let timer5, timerEventStream5 = createTimerAndObservable 500

Next, we convert each event on the “raw” event streams into our FizzBuzz event type:

// convert the time events into FizzBuzz events with the appropriate id
let eventStream3  =
   timerEventStream3
   |> Observable.map (fun _ -> {label=3; time=DateTime.Now})

let eventStream5  =
   timerEventStream5
   |> Observable.map (fun _ -> {label=5; time=DateTime.Now})

Now, to see if two events are simultaneous, we need to compare them from the two different streams somehow.

It’s actually easier than it sounds, because we can:

• combine the two streams into a single stream:
• then create pairs of sequential events
• then test the pairs to see if they are simultaneous
• then split the input stream into two new output streams based on that test

Here’s the actual code to do this:

// combine the two streams
let combinedStream =
    Observable.merge eventStream3 eventStream5

// make pairs of events
let pairwiseStream =
   combinedStream |> Observable.pairwise

// split the stream based on whether the pairs are simultaneous
let simultaneousStream, nonSimultaneousStream =
    pairwiseStream |> Observable.partition areSimultaneous

Finally, we can split the nonSimultaneousStream again, based on the event id:

// split the non-simultaneous stream based on the id
let fizzStream, buzzStream  =
    nonSimultaneousStream
    // convert pair of events to the first event
    |> Observable.map (fun (ev1,_) -> ev1)
    // split on whether the event id is three
    |> Observable.partition (fun {label=id} -> id=3)

Let’s review so far. We have started with the two original event streams and from them created four new ones:

• combinedStream contains all the events
• simultaneousStream contains only the simultaneous events
• fizzStream contains only the non-simultaneous events with id=3
• buzzStream contains only the non-simultaneous events with id=5

Now all we need to do is attach behavior to each stream:

//print events from the combinedStream
combinedStream
|> Observable.subscribe (fun {label=id;time=t} ->
                              printf "[%i] %i.%03i " id t.Second t.Millisecond)

//print events from the simultaneous stream
simultaneousStream
|> Observable.subscribe (fun _ -> printfn "FizzBuzz")

//print events from the nonSimultaneous streams
fizzStream
|> Observable.subscribe (fun _ -> printfn "Fizz")

buzzStream
|> Observable.subscribe (fun _ -> printfn "Buzz")

Let’s test it:

// run the two timers at the same time
[timer3;timer5]
|> Async.Parallel
|> Async.RunSynchronously

Here’s all the code in one complete set:

// create the event streams and raw observables
let timer3, timerEventStream3 = createTimerAndObservable 300
let timer5, timerEventStream5 = createTimerAndObservable 500

// convert the time events into FizzBuzz events with the appropriate id
let eventStream3  = timerEventStream3
                    |> Observable.map (fun _ -> {label=3; time=DateTime.Now})
let eventStream5  = timerEventStream5
                    |> Observable.map (fun _ -> {label=5; time=DateTime.Now})

// combine the two streams
let combinedStream =
   Observable.merge eventStream3 eventStream5

// make pairs of events
let pairwiseStream =
   combinedStream |> Observable.pairwise

// split the stream based on whether the pairs are simultaneous
let simultaneousStream, nonSimultaneousStream =
   pairwiseStream |> Observable.partition areSimultaneous

// split the non-simultaneous stream based on the id
let fizzStream, buzzStream  =
    nonSimultaneousStream
    // convert pair of events to the first event
    |> Observable.map (fun (ev1,_) -> ev1)
    // split on whether the event id is three
    |> Observable.partition (fun {label=id} -> id=3)

//print events from the combinedStream
combinedStream
|> Observable.subscribe (fun {label=id;time=t} ->
                              printf "[%i] %i.%03i " id t.Second t.Millisecond)

//print events from the simultaneous stream
simultaneousStream
|> Observable.subscribe (fun _ -> printfn "FizzBuzz")

//print events from the nonSimultaneous streams
fizzStream
|> Observable.subscribe (fun _ -> printfn "Fizz")

buzzStream
|> Observable.subscribe (fun _ -> printfn "Buzz")

// run the two timers at the same time
[timer3;timer5]
|> Async.Parallel
|> Async.RunSynchronously

The code might seem a bit long winded, but this kind of incremental, step-wise approach is very clear and self-documenting.

Some of the benefits of this style are:

• I can see that it meets the requirements just by looking at it, without even running it. Not so with the imperative version.
• From a design point of view, each final “output” stream follows the single responsibility principle – it only does one thing – so it is very easy to associate behavior with it.
• This code has no conditionals, no mutable state, no edge cases. It would be easy to maintain or change, I hope.
• It is easy to debug. For example, I could easily “tap” the output of the simultaneousStream to see if it contains what I think it contains:

// debugging code
//simultaneousStream |> Observable.subscribe (fun e -> printfn "sim %A" e)
//nonSimultaneousStream |> Observable.subscribe (fun e -> printfn "non-sim %A" e)

This would be much harder in the imperative version.

¶Summary

Functional Reactive Programming (known as FRP) is a big topic, and we’ve only just touched on it here. I hope this introduction has given you a glimpse of the usefulness of this way of doing things.

If you want to learn more, see the documentation for the F# Observable module, which has the basic transformations used above. And there is also the Reactive Extensions (Rx) library which shipped as part of .NET 4. That contains many other additional transformations.

G-Machine 是一种通过图规约来对函数式语言程序求值的抽象架构。
与组合子规约不同，组合子规约的control是从表达式图本身动态导出的，而G-Machine是由通过编译Application表达式导出的指令序列指定的。

FP的程序基本上都可以用一个表达式的图表示，图计算机就是对这个图求值的机器，总的说来对图的求值是一个不停合并图上的节点生产新节点的过程。

例如：

let x = 2 + 3 in 
  x * x

先计算出5，然后创建一个新的节点 5 * 5，然后再对这个节点求值，于是求值过程中就产生了很多临时的节点，这些中间节点也被叫做是 spine，求值过程是沿着 spine 进行的。

但是这样就产生了很多额外的开销，lambda lifting 里提到：可以把程序里，很多捕捉了外围绑定的闭包函数中的这些绑定，转换成函数的参数，从而消除闭包，得到的这个函数就可以自由脱离作用域，被静态的编译到机器码里。这些被 float out 的函数也叫 supercombinator.

在上面的代码中，如果不创建新的节点，顺序计算完了第一个 x，第二个 x 还会再被算一遍。

Spineless reduction 的概念：只有当面临需要重复计算的情况时，才去创建节点，不然就一路顺序算下去

• Graph reduction
• Graph reduction machine
• https://www.zhihu.com/question/54834531/answer/144213668

G⁺ 细菌的细胞壁外层主要由 厚度约 20–80 nm 的肽聚糖（peptidoglycan） 组成，这层结构密集且富含交联的糖肽链，能够在脱色步骤中形成物理屏障，阻止酒精/丙酮的渗透，从而保留结晶紫‑碘复合物。

与 G⁻ 细菌不同，G⁺ 细菌没有外膜（outer membrane）和脂多糖（LPS）层。外膜的缺失使得脱色剂难以进入细胞内部，进一步加强了紫色的保留。

某些 G⁺ 细菌在细胞壁上表达的酶（如酸性磷酸酶）可与染料形成更为稳定的复合物，进一步提升染色的持久性。

在呼吸道痰涂片中出现 “有荚膜的双球菌（capsulated diplococci）”，最典型的病原体是 肺炎链球菌（Streptococcus pneumoniae）。它是一种 革兰氏阳性（G⁺）、α‑hemolytic、嗜血清素 的双球菌，表面包裹有厚厚的多糖荚膜，正是该荚膜赋予它在显微镜下呈现明显的荧光或“胶状”外观。

在痰涂片或血培养的显微镜检查中，观察到 G⁺ 双球菌提示肺炎链球菌感染的可能性较大，帮助临床医生在培养结果出来前就能启动经验性抗生素治疗（如 β‑lactam 类药物）。

肺炎链球菌的荚膜多型性（> 90 种血清型）是疫苗设计的核心依据，同时也影响抗体介导的吞噬作用。了解其 G⁺ 特性有助于解释为何某些血清型（如 3 型）在免疫逃逸方面更具优势。

先来看看第一个方案 —— CRDT（Conflict-free Replicated Data Type，无冲突可复制数据类型）是一类数据结构，它保证了在分布式节点（或多客户端）上进行离线/并发更新后，无需中心协调、也无需人工干预，通过“合并策略”就能得到一致的最终状态。

核心思想是：所有并发操作都是幂等（idempotent）、可交换（commutative）的。

常见类型有：
一、G-Counter（只能增计数器）
二、PN-Counter（可增可减计数器）
三、LWW-Register（最后写入胜出）
四、结合 JSON 的树型 CRDT（如 Automerge / Yjs）

更多原理可参考 Decipad 博客“Collaborative and Offline Editing Using CRDTs”^[1]。

有一个挺有趣的 Rust 项目 Loro: Make your JSON data collaborative and version-controlled with CRDTs

假设我的项目信息编辑页面允许多人实时/离线修改某个研究项目的“名称”、“描述”字段，前端用 SvelteKit + GraphQL 获取和提交变更：

┌── 用户 A 离线修改了 “description” 的若干段文本  
└── 用户 B 同时在线修改了同一字段的其他段落  

如果后端使用 CRDT（比如把 description 用 JSON-CRDT 存储），两次修改只要在任意顺序合并都能得到完整的内容：

首先，A 客户端本地 apply 操作并缓存，恢复网络后推给服务器；
然后，服务器用 CRDT merge(A.delta, B.delta)，得到一致文档
最后，服务器广播新文档到所有客户端，A/B 均得到相同结果

好了说点实际符合业务场景的方案，首先想到的是悲观锁（Pessimistic Locking） ，思路是：用户打开编辑界面时，向后端申请“锁” → 其它用户尝试编辑时被拒绝 → 编辑完成后释放锁/超时自动释放。

假如有一个这样的锁表：

CREATE TABLE project_lock (
    project_id UUID PRIMARY KEY,
    locked_by  UUID NOT NULL,
    expires_at TIMESTAMPTZ NOT NULL
);

可以在事务内申请它：

const now = new Date();
const expires = new Date(now.getTime() + 5*60*1000); // 5 分钟后过期
await prisma.$transaction(async tx => {
    const existing = await tx.project_lock.findUnique({ where:{ project_id } });
        
    if (existing && existing.expires_at > now) {
	    throw new Error('项目正被人编辑');
	}
        
    await tx.project_lock.upsert({
        where: { project_id },
        update: { locked_by: userId, expires_at: expires },
        create: { project_id, locked_by: userId, expires_at: expires }
    });
});

释放锁就直接从锁表里删掉对应的数据即可：

await prisma.project_lock.delete({ where:{ project_id } });

前端的话，大概就是：

在进入编辑前请求一下 /api/project/:id/lock 之类的 API，失败则提示“被占用”；
在 onbeforeunload 时执行 /unlock；
超时后后端自动允许新锁。

第二个方案是乐观并发控制（Optimistic Concurrency） ：记录资源的版本号或时间戳；客户端提交更新时带上自己的版本号，后端检查版本是否一致，不一致则认为冲突，返回 409，由客户端告知用户“数据已过期，请刷新后合并”。

具体实现中，可以尝试在 project 表加上 version INT NOT NULL DEFAULT 1, updated_at TIMESTAMPTZ ，然后更新项目时：

async updateProject(parent, { id, version, input }, ctx) {
    const result = await prisma.$executeRaw`
    UPDATE project
        SET name        = ${input.name},
            description = ${input.description},
            version     = version + 1,
            updated_at  = now()
    WHERE id = ${id} AND version = ${version}
	`;
    if (result === 0) {
	    throw new ConflictException('版本冲突，请刷新后重试');
    }
    return prisma.project.findUnique({ where:{ id } });
}

前端捕获到冲突错误可以用一个弹窗提示“另有用户已更新此项目，是否合并/重新加载？” 之类的玩意儿。

第三个方案是：操作转化（Operational Transformation，OT）

也就是记录用户每次的“操作”（insert/delete at position），服务器根据历史操作序列对并发操作做转化（transform），确保先到达的操作调整后再应用后到达的。

有一些实现案例：
一、ShareDB（Node.js）
二、Google Docs 中的同步算法

具体实现的话，可能要现在前端逐字符/块地包装成操作并 WebSocket 推送，服务器再维护一个“操作历史队列”，每来一个 op 就 transform 并 broadcast，而客户端收到广播后，按顺序 replay 保证视图一致。

最后可能还可以用事件溯源（Event Sourcing）+ 场景命令模式来实现：

不直接存状态，而是存所有“命令 / 事件”（Event），回放事件得到当前状态。冲突通过合并策略或补偿事件（Compensating Events）解决。

例如：
在每次更新时推送 ProjectUpdated { projectId, fieldsChanged, userId, timestamp } ，
然后写入事件存储（如 Kafka / EventStoreDB），
读端 Consumer 按顺序重建最新状态或按领域聚合 ，
最后在并发时如果两个事件都修改了同一字段，可在写端做校验/补偿，或在读端做最后写入胜出等策略 。

总结来说，

• CRDT 最擅长 去中心化、离线编辑、自动合并；
• 若不引入 CRDT，可根据业务侧重点选用：
  1. 悲观锁 → 强制串行编辑，简单粗暴；
  2. 乐观并发 → 适合大多数业务场景，成本低；
  3. OT → 适合富文本或实时协同场景，复杂度中等；
  4. 事件溯源 → 适合需要全历史审计、可回放的场景。

举个例子：

假设有两个数据库模型：User（用户）和 Post（帖子），一个用户可以有多篇帖子（一对多关系）。

现在，需要获取前 10 个用户以及他们各自的所有帖子。

一种有问题的 ORM 实现（或不当的使用方式）可能会这样执行：

1. 第一次查询 (The “1”): 获取前 10 个用户。

   SELECT * FROM User LIMIT 10;

2. 接下来的 N (=10) 次查询 (The “N”): 对于上一步获取到的每一个用户，单独执行一次查询来获取该用户的帖子。

   -- 用户 1 SELECT * FROM Post WHERE authorId = 1; -- 用户 2 SELECT * FROM Post WHERE authorId = 2; -- 用户 3 SELECT * FROM Post WHERE authorId = 3; -- ... 直到 用户 10 SELECT * FROM Post WHERE authorId = 10;

在这个场景下，总共执行了 1 + 10 = 11 次数据库查询。如果 N 的值很大（比如获取 1000 个用户），就会产生 1001 次查询，这对数据库造成巨大的、不必要的压力，并显著增加应用程序的响应时间。每一次数据库交互都有网络延迟和数据库处理的开销，N+1 次查询会将这些开销放大 N 倍。

N+1 问题通常源于 ORM 处理关联数据的方式，特别是与“懒加载”（Lazy Loading）相关的策略。懒加载是指只有在显式访问关联属性时，ORM 才会去数据库加载这些数据。虽然这在某些情况下可以避免加载不需要的数据，但如果在循环中访问关联属性，就很容易触发 N+1 问题。

然而，问题的根源在于没有有效地预先加载（或批量加载）所需的关联数据。即使不使用严格意义上的懒加载，如果 ORM 在处理关联查询时不够智能，采用了逐个获取关联对象的策略，同样会产生 N+1 查询。

在 Prisma 出现之前或在其他 ORM 中，解决 N+1 问题常见的方法包括：

1. 预先加载（Eager Loading）: 在执行初始查询时，就明确指示 ORM 同时将关联数据也查询出来。这通常通过 SQL 的 JOIN 操作实现。例如，一次性查询出用户和他们的帖子。虽然这减少了查询次数，但复杂的 JOIN 可能会导致查询本身变得庞大和低效，并可能返回冗余数据。
2. 批量加载（Batch Loading）: 先执行初始查询获取父对象列表，然后收集所有父对象的 ID，在第二次查询中使用 WHERE IN (...) 子句一次性加载所有相关的子对象。这种方式通常需要两次查询，但避免了 N 次单独的查询。

Prisma ORM 在设计上就考虑了 N+1 问题，并提供了一种既方便开发者又高效的解决方案。当使用 Prisma Client 查询数据并需要包含关联模型时，Prisma 会自动优化查询，避免产生 N+1 查询，主要通过关系查询（Relation Queries）中的 include 选项或嵌套读取（nested reads）来实现这一点：

假设想获取所有用户及其发布的帖子，使用 Prisma Client，可以这样写：

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

async function getUsersWithPosts() {
  const usersWithPosts = await prisma.user.findMany({
    include: {
      posts: true, // 指示 Prisma 加载关联的 posts
    },
  })
  // usersWithPosts 包含了用户列表，每个用户对象中都有一个 posts 数组
  console.log(usersWithPosts)
}

getUsersWithPosts()
  .catch((e) => {
    throw e
  })
  .finally(async () => {
    await prisma.$disconnect()
  })

当执行上述查询时，Prisma 不会 生成 N+1 个 SQL 查询。而是首先会分析请求，并将其转化为数量非常有限的高效 SQL 查询。对于上面这个一对多关系的 include 查询，Prisma 通常会执行以下两步（类似于批量加载策略）：

1. 查询父模型: 获取所有 User 记录。

   SELECT "public"."User"."id", "public"."User"."name", /* ... other user fields */ FROM "public"."User" WHERE 1=1

2. 查询关联的子模型: 使用上一步获取到的所有用户 id，通过 WHERE IN (...) 子句一次性查询所有相关的 Post 记录。

   SELECT "public"."Post"."id", "public"."Post"."title", "public"."Post"."authorId", /* ... other post fields */ FROM "public"."Post" WHERE "public"."Post"."authorId" IN ($1, $2, $3, ...) /* 这里的 $1, $2, ... 是第一步查到的用户 ID 列表 */

Prisma Client 在内存中将这两次查询的结果高效地组合起来，最终返回嵌套的、符合 TypeScript 类型的数据。

¶Refs.

• Stack Overflow: What is the N+1 selects problem in ORM?
• Prisma Docs: Solving the N+1 problem

在这个 PR 中支持了 Native AOT
https://github.com/commandlineparser/commandline/pull/913

除此之外，还有一个更加精巧的 F# 库可以用，只有两百多行：
https://github.com/B2R2-org/FsOptParse/

AOT 后的大小很可观，并且支持 full trim.

用例：

(** defines a state to pass to the option parser *)
type opts =
  {
    optX : int;
    optY : bool;
    optZ : string;
  }

(** default option state *)
let defaultOpts =
  {
    optX = 0;
    optY = false;
    optZ = "";
  }

(*
  An example command line specification, which is a list of Options.
  Each Option describes a command line option (switch) that is specified with
  either a short (a single-dash option) or long option (a double-dash option).
*)
let spec =
  [
    (* This option can be specified with -x <NUM>. There is an extra argument to
       specify a value in integer. *)
    Option ((* description of the option *)
            descr="this is a testing param X",
            (* how many extra argument must be provided by a user? *)
            extra=1,
            (* callback sets up the option and returns it *)
            callback=(fun opts arg -> {opts with optX=(int) arg.[0]}),
            (* use a short option style -x *)
            short="-x"
           );

    (* This option can be specified with -y. There is no extra argument. This
       option just sets a flag, optY. *)
    Option ((* description of the option *)
            descr="this is a testing param Y",
            (* set the option to be true *)
            callback=(fun opts _ -> {opts with optY=true}),
            (* use a short option style (-y) *)
            short="-y",
            (* also use a long option style (--yoohoo) *)
            long="--yoohoo"
           );

    (* A dummy option to pretty-print the usage *)
    Option ((* description of the option *)
            descr="",
            dummy=true
           );
    Option ((* description of the option *)
            descr="[Required Options]",
            descrColor=System.ConsoleColor.DarkCyan,
            dummy=true
           );

    (* The third option is a required option. In other words, option parsing
       will raise an exception if this option is not given by a user. This
       option takes in an additional integer argument, and set it to the global
       variable z. *)
    Option ((* description of the option *)
            descr="required parameter <STRING> with an integer option",
            (* callback to set the optZ value *)
            callback=(fun opts arg -> {opts with optZ=arg.[0]}),
            (* specifying this is a required option *)
            required=true,
            (* one additional argument to specify an integer value *)
            extra=1,
            (* use only a long option style *)
            long="--req"
           );
  ]

let _ =
  let prog = "opttest.fsx"
  let args = System.Environment.GetCommandLineArgs ()
  let usageGetter () = "[Usage]\n  %p %o"
  try
    let left, opts = optParse spec usageGetter prog args defaultOpts
    printfn "Rest args: %A, x: %d, y: %b, z: %s"
      left opts.optX opts.optY opts.optZ
    0
  with
    | SpecErr msg ->
        eprintfn "Invalid spec: %s" msg
        exit 1
    | RuntimeErr msg ->
        eprintfn "Invalid args given by user: %s" msg
        usagePrint spec prog usageGetter (fun () -> exit 1)

中性粒细胞的主要作用体现在免疫防御和炎症调控上。

首先，它们通过趋化因子（如IL-8、LTB4）和黏附分子（如整合素）从骨髓快速募集到感染或损伤部位，寿命通常仅为数小时至几天，却能高效执行任务。

其次，它们通过吞噬作用（phagocytosis）摄取细菌、真菌或其他病原体，并在吞噬体-溶酶体融合后释放颗粒内容物杀死目标。这种颗粒包括原初颗粒（azurophilic granules，富含髓过氧化物酶和防御素）、次级颗粒（specific granules，含乳铁蛋白和胶原酶）以及三级颗粒（gelatinase granules，含明胶酶）。

中性粒细胞还能形成中性粒细胞外陷阱（NETs），一种DNA-蛋白复合网状结构，用于捕获和杀死大颗粒病原体，如某些细菌或寄生虫。这些机制确保了中性粒细胞在急性炎症中的“第一响应者”角色，例如在肺炎或创伤中，它们能限制感染扩散，防止系统性败血症。

但中性粒细胞释放的许多物质本质上是有毒的，这是其杀菌机制的核心，为了高效消灭病原体，它们必须产生非特异性破坏性工具。

这些毒性物质主要包括活性氧簇（ROS，如超氧化物和过氧化氢，由NADPH氧化酶产生）、反应性氮中间体（RNI）、蛋白水解酶（如弹性蛋白酶、胶原酶和MMP-9，即基质金属蛋白酶-9）以及阳离子蛋白（如防御素和细菌素）。

ROS通过氧化损伤病原体DNA和蛋白质，RNI则干扰微生物代谢，而蛋白酶则降解细胞壁或外膜。

在正常生理条件下，这些释放是局部的、短暂的，受调控以最小化对宿主组织的损伤（例如，通过抗氧化酶（如超氧化物歧化酶）或蛋白酶抑制剂（如α1-抗胰蛋白酶）来平衡。）

但当激活信号持续存在时，如在慢性炎症环境中，中性粒细胞会过度募集和脱颗粒，导致毒性物质外溢，引发旁观者效应（bystander damage），损伤邻近健康细胞和基质。

在COPD这一慢性气道炎症疾病中，中性粒细胞的作用被放大为病理驱动因素。

COPD患者常伴随吸烟或环境暴露诱发的氧化应激，导致气道上皮释放大量趋化因子（如CXCL8/IL-8和LTB4，脂氧合酶途径产物），从而持续募集中性粒细胞。

这些细胞在肺泡和支气管黏膜定植后，释放MMP-9（促进基质降解和气道重构）、弹性蛋白酶（破坏弹性纤维，导致肺气肿）和LTB4（进一步放大炎症级联）。

而 PDE4（磷酸二酯酶4）能够降解cAMP（环腺苷酸），从而增强中性粒细胞的趋化、脱颗粒和ROS产生。

所以临床上，PDE4 抑制剂如罗氟司特（roflumilast）被批准用于重度COPD，以降低中性粒细胞介导的炎症，减少急性加重风险。

例如 xxx.yyy.zzz 是前端，xxx.yyy.zzz/api 是后端，后端基于 NestJS 用了 better-auth 会自动挂 /auth 路径。

Nginx 跑在 Docker 容器里，配置和证书从宿主机挂载进去：

• /opt/nginx/conf.d → /etc/nginx/conf.d
• /opt/nginx/ssl → /etc/nginx/ssl
• /opt/nginx/nginx.conf → /etc/nginx/nginx.conf

容器通过 extra_hosts: host.docker.internal:host-gateway 访问宿主机服务，所以前后端进程可以继续跑在宿主机上（比如 PM2 管理），Nginx 容器只做反代。

遇到的第一个坑：/api/auth/* 和 /api/* 不能用同一个 rewrite 规则。

如果这么写：

location /api/ {
  proxy_pass http://host.docker.internal:<backend>/;
}

Nginx 会把 /api 前缀裁掉。于是 /api/auth/sign-in/email 变成了 /auth/sign-in/email，但 better-auth 挂在 /api/auth/*，直接 404。

正确的做法是分开处理。更麻烦的是业务身份接口 /auth/me 也存在，如果后端业务接口是 /auth/me，而认证框架是 /api/auth/*，那 /api/auth/me 应该转发给业务而不是认证框架。

正确顺序：

location = /api/auth/me {
  # 精确匹配，业务身份接口
  rewrite ^/api(.*)$ $1 break;
  proxy_pass http://host.docker.internal:<backend>;
}

location ^~ /api/auth/ {
  # 认证框架路由，保留前缀
  proxy_pass http://host.docker.internal:<auth-port>;
}

location ^~ /api/ {
  # 其余 API，裁掉 /api
  rewrite ^/api(.*)$ $1 break;
  proxy_pass http://host.docker.internal:<backend>;
}

location / {
  # 前端
  proxy_pass http://host.docker.internal:<frontend>;
}

这里的顺序很重要。Nginx 匹配规则是：精确匹配 = 优先，然后是前缀匹配 ^~，然后是正则匹配，最后是普通前缀匹配。^~ 表示一旦匹配成功就不再检查正则。

let int_pow base exponent =
  if exponent < 0 then negative_exponent ();
  if abs base > 1
     && (exponent > 63
         || abs base > Pow_overflow_bounds.int_positive_overflow_bounds.(exponent))
  then overflow ();
  int_math_int_pow base exponent
;;

其中 int_math_int_pow() 由 C 实现:

external int_math_int_pow : int -> int -> int = "Base_int_math_int_pow_stub" [@@noalloc]

其实现在 src/int_math_stubs.c 中:

static int64_t int_pow(int64_t base, int64_t exponent) {
  int64_t ret = 1;
  int64_t mul[4];
  mul[0] = 1;
  mul[1] = base;
  mul[3] = 1;

  while (exponent != 0) {
    mul[1] *= mul[3];
    mul[2] = mul[1] * mul[1];
    mul[3] = mul[2] * mul[1];
    ret *= mul[exponent & 3];
    exponent >>= 2;
  }

  return ret;
}

这是一个四分快速幂的实现，它是二分快速幂的一种变种。二分快速幂将指数分为两部分，然后递归地计算每一部分的结果。
而四分快速幂将指数分为四部分，然后递归地计算每一部分的结果。
这里通过将指数右移2位（相当于除以4）和使用位与操作来实现，进一步减少了乘法次数。

主要步骤：

• 初始化返回值ret为1，和一个包含4个元素的数组mul, mul[0]和mul[3]被初始化为1， mul[1]被初始化为基数
• 当指数不为0时，执行循环, 在每次循环中，首先更新mul数组的值

  mul[1]是基数和mul[3]的乘积，mul[2]是mul[1]的平方，mul[3]是mul[2]和基数的乘积

• 然后，将ret乘以mul数组中的一个元素, 这个元素的索引是指数和3的位与运算的结果

  这样做的目的是为了选择正确的乘数，因为指数被分解为4的倍数

• 最后，将指数右移2位，相当于将指数除以4
• 当指数变为0时，循环结束，返回ret

这个实现的优点是它可以在对数时间内计算出幂运算，而且每次循环只需要4次乘法。这比标准的二分快速幂算法需要的乘法次数更少。

• OCaml Survey: Developers’ Perception, Interest, and Perceived Barriers
• Announcing the ORCHIDE Project: Powering Satellite Innovation
• Dynarrays, unboxed (with local dummies) #12885
• Stdlib priority queues #12871
• Compile recursive bindings in Lambda #12596
• Add short syntax for dependent functor types #12828
• [shapes] Add support for project-wide occurrences #12508
• Make the character set for OCaml source code officially UTF-8. #1802
• Add thread local storage #12719

¶Videos

• “Melange: The next frontier in type-safe web development” by Dillon Mulroy - RVAJS 2023
• Trying out OCaml TUI framework Mint Tea!
• A TUI chat in OCaml 🐫
• [Building a Game Engine… with OCaml ?! [Part 1]](https://www.youtube.com/watch?v=1XpUaTnssQE

¶Blogs

• What’s possible with Melange
• Access inferred types
• Using Menhir to parse into idiomatic JS (TypeScript) structures
• Why constructors are not curried?
• Practical example of applicative vs generative functors?
• Compiler optimization on flattening ADT for less boxing?
• How to express Koka home page example?
• Parsing with Binary String Pattern Matching

¶Highlighted Projects

• grid: A tiny library for two-dimensional arrays
• A fun little TUI framework for OCaml
• ocaml-ts-mode: Ocaml mode for emacs using treesitter
• create-melange-app: An example app created by create-melange-app
• ppx_protocol_conv: Pluggable serialization and deserialization of ocaml data strucures based on type_conv
• spatial-shell: Spatial Shell is a daemon implementing a spatial model inspired by Material Shell, for i3 and sway. More precisely, it organizes your windows within a grid whose rows are the workspaces of your favorite WM.
• Fixgen: A language agnostic fixture generator
• opam-nix: Turn opam-based OCaml projects into Nix derivations
• Blink: A pure OCaml HTTP client for Riot
• colors: A pure OCaml library for manipulating colors in different color spaces.
• miilfy: A web annotation server built with the same principles as Git

¶New Releases

• Roit v0.0.7: An actor-model multi-core scheduler for OCaml 5 🐫
• [CAStore: A portable pure OCaml CA Store, with no dependencies, inspired by Elixir’s :castore.](https://github.com/leostera/castore)
• Lean-OCaml 1.0: A Web Application for Learning OCaml
• cmarkit 0.3.0" CommonMark parser and renderer for OCaml
• dream-html 2.0.0: A library for generating HTML
• Caisar: A platform under active development at CEA LIST, aiming to provide a wide range of features to characterize the safety and robustness of artificial intelligence based software.
• RFSM 2.0: A toolset for describing and simulating StateChart-like state diagrams.
• Zbg 2.0: zbg (short for Zero Bullshit Git) is a CLI tool for using git efficiently.

• [ANN][PREVIEW] Play with project-wide occurrences for OCaml!
• [Dune]: Add link flags ocamlmklib when using ctypes stubs. #8784
• OCaml Software Foundation: January 2024 update
• [Apprendre à programmer avec OCaml](Apprendre à programmer avec OCaml)
• [Call for Speakers for the 2024 Carolina Code Conference is open until April 15th](https://discuss.ocaml.org/t/call-for-speakers-for-the-2024-carolina-code-conference-is-open-until-april-15th/13827)
• [OCaml]: feature request: better errors #11924
• Ocsigen: summary of recent releases

¶Discussion

• Benchmark between open-addressing and closed-addressing hashtbl
• Examples of Caqti infix?
• Why can’t I create a project with non-ASCII characters?
• Old self-taught vs. uni debate; Landscape for former; Jane Street
• Is there an easy way to read the values from a toml file?
• Generate typed AST fragments
• Partially apply function accepting multiple modules and keep polymorphic types
• Printing Unicode Characters on Different Platforms

¶Videos

• Verifying an Effect-Based Cooperative Concurrency Scheduler in Iris by Adrian Dapprich

¶Blogs

• Advice for combining multiple monads
• Writing ctypes bindings to system shared libraries for bytecode targets via the dune ctypes stanza

¶Highlighted Projects

• Grace: A fancy diagnostics library that allows your compilers to exit with grace
• meta-pp: Meta-preprocessor for OCaml
• ppx_stage: Staged metaprogramming in stock OCaml
• [Cmarkit is an OCaml libary for parsing the CommonMark specification.](https://erratique.ch/software/cmarkit)
• [Brr is a toolkit for programming browsers in OCaml with the js_of_ocaml compiler. It provides:](https://erratique.ch/software/brr)
• [Zipc is an in-memory ZIP archive and deflate compression codec for OCaml.](https://erratique.ch/software/zipc)
• ocaml-gccjit: OCaml bindings for libgccjit
• ocaml-m17n: Multilingualization for the OCaml source code
• ocamlearlybird: OCaml debug adapter
• otoml: TOML parsing, manipulation, and pretty-printing library for OCaml (fully 1.0.0-compliant)
• ocaml-decoders: Elm-inspired decoders for Ocaml
• ez_toml: A library to parse and print TOML files

¶New Releases

• Oma: OCaml implementation of ‘Two Simplified Algorithms for Maintaining Order in a List’
  • [ANN] First release of oma
  • Two Simplified Algorithms for Maintaining Order in a List
• ocamlearlybird: v1.3.0
  • [ANN] Ocamlearlybird just got ability to inspect opaque/abstract values
• validate: OCaml Data Validation library
  • [ANN] Validate - A New Library for Data Validation
• sarif v2.1.0: Static Analysis Results Interchange Format (SARIF) For OCaml
  • [ANN] sarif 0.1.0 - Static Analysis Results Interchange Format (SARIF) For OCaml
• [ANN] New release of Menhir (20231231)

o-新鲜事儿

• OCaml 5.1.0 released

• [ANN] dune 3.14

• code search

• [ANN] ocaml.codes, code search for OPAM packages

• 用 livegrep 基于 opam 包的源码做的代码搜索，还挺方便的。

• Announcing Melange 3

• [ANN] Melange 3.0

• Learn-OCaml 1.0 is out!

• https://ocaml-sf.org/learn-ocaml-public/

• GitHub - owlbarn/owl: Owl - OCaml Scientific Computing @ http://ocaml.xyz

• Owl project concluding

• 经过八年的维护，Owl项目即将终止

¶

o-视频

• Inferring Locality in OCaml | OCaml Unboxed

• OCaml Locals Save Allocations | OCaml Unboxed

• Ocsigen: Developing Web and mobile applications in OCaml – Jérôme Vouillon & Vincent Balat

• Verifying an Effect-Based Cooperative Concurrency Scheduler in Iris by Adrian Dapprich

¶

o-博客 / 文章 / 帖子

• Introducing DBCaml, Database toolkit for OCaml

• Building a Connnection Pool for DBCaml on top of riot

• Generating static and portable executables with OCaml

• OCaml编译器没有内置生成静态可移植可执行文件的特性，这里提到了一些技巧

• Analog of Promise.any() for Multicore OCaml

• Printf vs. Format?

• How to represent tuples in AST?

• How do I pass an unsigned char * (an array of bytes representing binary data) from C to OCaml?

¶

o-未来

• How do we want to present OCaml to the World on OCaml.org?

• 一个问卷，用于更好的改进 ocaml.org 有关学术和工业应用板块的内容。

• Feedback / Help Wanted: Upcoming OCaml.org Cookbook Feature

• ocaml.org 准备上线一个cookbook页面，放一些如何用OCaml的生态解决常见需求的资源

• State of compaction in OCaml 5?

• OCaml 5.2 的 compact heap 会将未使用的内存返回给操作系统。在 OCaml 5 的 GC 中，小于 128byte 的块用大小隔离池进行管理，比如有一个池，处理大小为 3byte 的分配，另一个池处理大小为 4byte 的分配等等，这样的池在每个Domain里都有。用这个方法分配速度很快，因为不用找合适的内存间隙了，只要找正确的池大小就行。

¶

o-值得被注意的项目

• GitHub - mbarbin/vcs: A versatile OCaml library for Git interaction

• A Versatile OCaml Library for Git Interaction - Seeking Community Feedback

• GitHub - dbcaml/dbcaml: DBCaml is a database library for OCaml

• DBcaml, a new database toolkit built on Riot

• GitHub - c-cube/fuseau: [alpha] lightweight fiber library for OCaml 5

• [ANN] fuseau 0.1

• GitHub - issuu/ocaml-protoc-plugin: ocaml-protoc-plugin

• Taking over maintanence of a stale project

• GitHub - darrenldl/docfd: TUI multiline fuzzy document finder

• [ANN] Docfd: TUI multiline fuzzy document finder 2.2.0

• First beta release for OCaml 5.2.0.

• #12876 和 #12915 提供了 ThreadSanitizer 对 Power 和 s390x 上的 Linux 支持。

• #12677 和 #12889 实现了 Domain.DLS 的线程安全。

• #12924 和 #12930 提到了一个类型系统的错误和其修复方式（merged）:

module type S = sig
  type t [@@immediate]
end

type t = (module S with type t = int)
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
(*
Error: In this with constraint, the new definition of t
       does not match its original definition in the constrained signature:
      Type declarations do not match:
         type t
       is not included in
         type t [@@immediate]
       The first is not an immediate type.
*)

• OCaml 4.14.2 released.

• Owl project restructured.

• Your Feedback Needed on OCaml Home Page Wireframe!

• Shape with us the New OCaml.org Community Area!

• OCaml Platform Newsletter: February 2024.

• 其中值得注意的是：探索 dune 和包管理的集成 和 opam 2.2 的 Windows Native support.

• OCaml Workshop 2024 at ICFP – announcement and call for proposals.

• Volunteers for ICFP 2024 Artifact Evaluation Committee (AEC).

• Odoc 3.0 planning.

• Opam-repository: Updated documentation, retirement and call for maintainers.

• kit-ty-kate 退休啦。

¶论文

• Chemoinformatics and structural bioinformatics in OCaml.

¶帖子/文章

• OCaml for building shared libraries: how are the ergonomics and performance?

• Using Awk in Kakoune to Generate SQL Types for OCaml.

• Eio 1.0 Release: Introducing a new Effects-Based I/O Library for OCaml.

• [BLOG] The Flambda2 Snippets, by OCamlPro.

• The Flambda2 Snippets, Episode 0.

• CPS Representation and Foundational Design Decisions in Flambda2.

• Monadic Library for Eio Capabilities?

• Is there any consensus on which type to unify on for errors in result types? What’s your preference?

• Create opam switch specifying custom C compiler.

¶视频

• Outreachy Presentations for the December 2023 Round.

• Taking Erlang to OCaml 5 (with Leandro Ostera).

• OCaml Unboxed: An Exploration of Jane Street’s Experiments with OCaml.

• OCaml for Fun & Profit: An Experience Report • Tim McGilchrist • YOW! 2023.

¶值得注意的项目

• Eio 1.0: Effects-based direct-style IO for multicore OCaml.

• icfp-2023-eio-tutorial: This tutorial covers how to convert an OCaml 4 program using Lwt for concurrency to use OCaml 5 and Eio.

• Down: An unintrusive user experience upgrade for the OCaml toplevel system (REPL).

• ocaml-rs: OCaml extensions in Rust.

• eio-trace: Trace visualisation tool for Eio programs.

• [ANN] DkCoder 0.1.0: A transparently installed OCaml 4.14 environment with one API: run a script.

• [ANN] Docfd 3.0.0: TUI multiline fuzzy document finder.

• [ANN] Ocaml-windows 5.1.1.

• 这里指的是 opam-cross-windows 支持 5.1.1 了，不是 Windows 支持。

• [ANN] Bindings to QuickJS.

• [ANN] ppx_minidebug 1.3.0: toward a logging framework.

• [ANN] iostream 0.2.

• [ANN] Js_of_ocaml 5.7.

¶有趣的项目

• ocaml-lua: Lua bindings for OCaml.

• csml: High-level bindings between .Net and OCaml.

• landmarks: A Simple Profiling Library for OCaml.

• Ttweetnacl: An OCaml module providing thin bindings to the TweetNaCl cryptographic library.

• cryptokit: A library of cryptographic primitives (ciphers, hashes, etc) for OCaml.

• llama: A library for building software-defined modular synthesizers in a declarative style.

• Immutable arrays #13097: This PR proposes to add immutable arrays to OCaml.
• Support running native debuggers in ocamltest #13199.
• The Pattern-Matching Bug: fix totality information by gasche · Pull Request #13152 · ocaml/ocaml.
• Add loongarch architecture support #11974.
• Add Stdlib.todo #13101.
• Enhancing the OCaml.org Community Page: Boosting UX and UI Based on User Research.
• Launching the First-Class Windows Project.

¶新消息

• [ANN] Project wide occurrences in Merlin and LSP.

• [ANN] opam 2.2.0 rc1 release.

• [ANN] First release of baby.

• baby is an OCaml library that offers several implementations of balanced binary search trees.

• [ANN] Preview of Stripe client and mock server - DkStdRestApis.

• [ANN] CAISAR release 2.0, a platform for characterizing AI safety and robustness.

• [ANN] Forester 4.1.

• [ANN] dream-html & pure-html 3.5.2

¶有价值的文章

• Keeping Up With the Compiler: How we Help Maintain the OCaml Language
• Explain mapping between OCaml memory model and C.
• Control structures – Xavier Leroy.
• 8 months of OCaml after 8 years of Haskell in production.
• Getting OCaml Through the Eye of a Needle.
• Secure From the Ground Up: Introducing the FIDES Project Combining RISC-V and MirageOS.
• Effective ML Through Merlin’s Destruct Command.
• Dinosaure’s website - Reproducibility!
• Experiments in JITting.
• How to write an efficient ‘cp -R’ clone with Eio?
• Generating infix extension nodes with Ppxlib.
• This made my day (float to string and string of float without loss of precision).
• Help with cryptic dependency cycle compile errors using dune build.
• Why does relaxed value restriction treat function types differently?
• Binding existentials in a non-uniform GADT.

¶有趣的项目

• ocaml-index 1.0 (latest) · OCaml Package: A tool that indexes value usages from cmt files.
• fileutils 0.6.4 (latest) · OCaml Package: API to manipulate files (POSIX like) and filenames.
• pure-html 3.5.2 (latest) · OCaml Package
• GitHub - fpottier/baby: A balanced binary search tree library for OCaml.
• GitHub - akabe/ocaml-jupyter: An OCaml kernel for Jupyter (IPython) notebook.
• Github - robur-coop/orb: check opam package reproductibility.
• Github - ocaml-multicore/dscheck: Experimental model checker for testing concurrent algorithms.

       ^o3
~/\_/\_|)
|/=_=\|
"     "

¶语言的发展

• Modular explicits #13275

• Add short syntax for dependent functor types #12828

• Add Pair module to standard library #13310

• Allow maximum number of domains to be specified as a OCAMLRUNPARAM parameter #13272

• Immutable arrays #13097

• Restore native armv7 support for NetBSD 10.0 #13161

• Add effect syntax #12309

• Add ThreadSanitizer support #12114

• A new abstract data type of enumerations in Set.Make(Ord).Enum #13195

• Stdlib priority queues #12871

• Aliasing == and != with explicit names #9080

• Memory cleanup at exit #12964

• A document type for error messages #13169

• Fix GC alarm regression #13318

• Implement O_APPEND on windows #13326

• Add missing functions from Array to Dynarray #13296

• Improve the type clash error message #12182

• Emphasize that Bigarray.int refers to the OCaml int type, and not the C int type #12298

• Effects with Lwt, a dead end for now?

• Changes in handling of Gc parameters and alarms in 5.2.0

¶新消息

• [ANN] Mopsa 1.0 – Modular Open Platform for Static Analysis

• [ANN] A small extension of Bigarray.Genarray adding iteration, mapping and folding

• [ANN] cudajit: Bindings to the cuda and nvrtc libraries

• [ANN] OCaml LSP 1.18.0

• [ANN] Ortac 0.3.0 Dynamic formal verification made easy

¶有价值的文章

• Combinations of Reusable Abstract Domains for a Multilingual Static Analyzer

• Fighting Mutation with Mutation in Living

• Type system and polymorphic let’s

• Using Docusaurus to document an OCaml project

• Exploring the Docusaurus+Odoc comboType system and polymorphic let’sExploring the Docusaurus+Odoc combo

• A (Possibly) Safer Interface to the Ctypes FFI

• OCaml FFI Sharp Edges – and How to Avoid them!

¶有趣的项目

• ocaml-libvirt OCaml bindings for libvirt

• Gitlab - MOPSA/MOPSA analyzer: stands for Modular and Open Platform for Static Analysis.

• GitHub - Heyji2/GenArrayIter: Adding iteration, mapping and folding to the ocaml BigArray.Genarrays module which provides arrays of arbitrary dimensions

• GitHub - mbarbin/bopkit: An educational project for digital circuits programming

• GitHub - dx3mod/rpmfile: A library for reading metadata from RPM packages.

• Github - gildor478/ocaml-fileutils: OCaml API to manipulate real files (POSIX like) and filenames

• Github - NathanReb/ocaml-api-watch: Libraries and tools to keep watch on you OCaml lib’s API changes

       ^o3
~/\_/\_|)
|/=_=\|
"     "

^~~~~~~~~~~~这其实是用 ASCII 画的一个骆驼。

¶语言的发展

• OCaml 5.2.1 released

• Feedback / Help Wanted: Upcoming OCaml.org Cookbook Feature

• Second beta release of OCaml 5.3.0

• Terrateam’s open source Ocaml repository

• [ANN] .mlx syntax dialect

• [ANN] opam 2.3.0 is out!

• Fun OCaml 2024 - Berlin - September 16+17, 2024

• Fun OCaml is an open source hacking event dedicated to OCaml enthusiasts and professionals around the globe!

• Simplify the build of cross compilers by shym · Pull Request #13526 · ocaml/ocaml

• “Mark-delay” performance improvement to major GC by NickBarnes · Pull Request #13580 · ocaml/ocaml

• Use WinAPI concurrency primitives on Windows ports (remove winpthreads) by MisterDA · Pull Request #13416 · ocaml/ocaml

• Atomic record fields by clef-men · Pull Request #13404 · ocaml/ocaml

¶视频

• All the talk recordings from FUN OCaml 2024 in Berlin, September 16 + 17, 2024.
• [ICFP24] Oxidizing OCaml with Modal Memory Management
• [OCaml24] Priodomainslib: Prioritized Fine-grained Parallelism for Multicore OCaml
• [OCaml24] ChorCaml: Functional Choreographic Programming in OCaml
• [OCaml24] Saturn: a library of verified concurrent data structures for OCaml 5
• Beyond the Basics of LSP: Advanced IDE services for OCaml
• Why Terrateam chose OCaml
• A Crash Course in OCaml Modules • Tim McGilchrist • YOW! 2015
• Outreachy May 2024 Demo
• Octane: A Query Builder for OCaml

¶讨论

• What are the biggest reasons newcomers give up on OCaml?
• Do you use “return” to describe a function?
• OCaml Cycle detection and Garbage Collector
• Modeling Rust trait objects subtyping relation via OCaml polymorphic variants
• Ocamldebug using dune
• Typesafe SQL with Octane.ml

¶文章

• Using Map and ppx yojson

• Correct syntax to add compare ppx

• Tiny educational concurrent I/O and promises library

• Good example of handwritten Lexer + Recursive Descent Parser?

• [NEW PART] Pragmatic Category Theory: Part 2 published!

• Pragmatic Category Theory | Part 1: Semigroup Intro

• Pragmatic Category Theory | Part 2: Composing Semigroups

• Installing OCaml on a mac m1 mini

• « A Case for Feminism in Programming Language Design »

• A Case for Feminism in Programming Language Design.pdf

• Vdom 0.3 brings Elm-style decoders to OCaml

¶生态

• Re2ocaml regexp compiler

• Eliom 11.1: Towards Web Assembly support

• [ANN] New releases of Merlin and OCaml-LSP

• New release of baby

• babyis an OCaml library that offers persistent sets and maps based on balanced binary search trees. It offers replacements for OCaml’sSetandMapmodules.

• [ANN] Dune 3.17

• [ANN] Jsont 0.1.0 – Declarative JSON data manipulation for OCaml

• [ANN] Release of Saturn 1.0

  • Saturn is a collection of concurrent-safe data structures designed for OCaml 5.

• [ANN] Areas and Adversaries

• [ANN] Release of cppo 1.8.0

• [ANN] capnp-rpc 2.0

• [ANN] Advent of Code project template

• [ANN] Testo 0.1.0 - a new testing framework for OCaml

• [ANN] vdom 0.3: functional UI applications now with custom event handlers

• Visualizing dependencies between Ocaml modules

• [ANN] mariadb 1.2.0

• [ANN] New release of Monolith

• [ANN] First release of hachis

• [ANN] Liquidsoap 2.3.0

• [ANN] dream-html & pure-html 3.5.2

• [ANN] Js_of_ocaml 5.9.0

• [ANN] ppx_deriving_ezjsonm

• [ANN] smaws preview release, an AWS SDK for OCaml using eio

• [ANN] aws-s3 4.0.1

• First release of cmdlang

• [ANN] Eliom 11 and Ocsigen Start 7

• [ANN] Jane Street OCaml extensions – now with developer tooling!